AddKvpItems method of the Msvm_VirtualSystemManagementService class
Adds key-value pairs to a virtual system.
Syntax
uint32 AddKvpItems(
[in] CIM_ComputerSystem REF TargetSystem,
[in] string DataItems[],
[out] CIM_ConcreteJob REF Job
);
Parameters
-
TargetSystem [in]
-
Type: CIM_ComputerSystem
A reference to the virtual computer system on which the key-value pairs will be added.
-
DataItems [in]
-
Type: string[]
An array of key-value pairs to be added. Each element of the array is an embedded instance of the Msvm_KvpExchangeDataItem class. This method fails if any of the specified key-value pairs already exists on the target system. This array can contain at most 128 elements.
-
Job [out]
-
Type: CIM_ConcreteJob
An optional parameter for monitoring progress of the operation represented by an instance of the CIM_ConcreteJob class, which is used if the method could not be executed synchronously. If the operation is executing asynchronously, the return value is 4096.
Return value
Type: uint32
This method returns one of the following values.
-
Completed with No Error (0)
-
Method Parameters Checked - Job Started (4096)
-
Failed (32768)
-
Access Denied (32769)
-
Not Supported (32770)
-
Status is unknown (32771)
-
Timeout (32772)
-
Invalid parameter (32773)
-
System is in used (32774)
-
Invalid state for this operation (32775)
-
Incorrect data type (32776)
-
System is not available (32777)
-
Out of memory (32778)
Remarks
Access to the Msvm_VirtualSystemManagementService class might be restricted by UAC Filtering. For more information, see User Account Control and WMI.
Examples
The following C# sample adds key-value pairs to a virtual system. The referenced utilities can be found in Common Utilities for the Virtualization Samples.
[!Important]
To function correctly, the following code must be run on the VM host server, and must be run with Administrator privileges.
using System;
using System.Management;
namespace HyperVSamples
{
class AddKvpItemsClass
{
static void AddKvpItems(string vmName, string itemName, string itemValue)
{
ManagementScope scope = new ManagementScope(@"root\virtualization", null);
ManagementObject virtualSystemService = Utility.GetServiceObject(scope, "Msvm_VirtualSystemManagementService");
ManagementBaseObject inParams = virtualSystemService.GetMethodParameters("AddKvpItems");
ManagementClass kvpExchangeDataItem = new ManagementClass(scope, new ManagementPath("Msvm_KvpExchangeDataItem"), null);
ManagementObject dataItem = kvpExchangeDataItem.CreateInstance();
dataItem["Data"] = itemValue;
dataItem["Name"] = itemName;
dataItem["Source"] = 0;
string[] dataItems = new string[1];
dataItems[0] = dataItem.GetText(TextFormat.CimDtd20);
ManagementObject vm = Utility.GetTargetComputer(vmName, scope);
inParams["TargetSystem"] = vm.Path.Path;
inParams["DataItems"] = dataItems;
ManagementBaseObject outParams = virtualSystemService.InvokeMethod("AddKvpItems", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
{
if (Utility.JobCompleted(outParams, scope))
{
Console.WriteLine("Resources were added successfully.");
}
else
{
Console.WriteLine("Failed to add resources");
}
}
else if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("Resources were added successfully.");
}
else
{
Console.WriteLine("Add virtual system Kvp items failed with error {0}", outParams["ReturnValue"]);
}
if (inParams != null)
{
inParams.Dispose();
}
if (outParams != null)
{
outParams.Dispose();
}
}
static void Main(string[] args)
{
if (args != null && args.Length != 3)
{
Console.WriteLine("Usage: AddKvpItems vmName itemName itemValue");
return;
}
AddKvpItems(args[0], args[1], args[2]);
}
}
}
The following VBScript sample adds key-value pairs to a virtual system.
[!Important]
To function correctly, the following code must be run on the VM host server, and must be run with Administrator privileges.
option explicit
dim objWMIService
dim managementService
dim fileSystem
const JobStarting = 3
const JobRunning = 4
const JobCompleted = 7
const wmiStarted = 4096
const wmiSuccessful = 0
Main()
'-----------------------------------------------------------------
' Main
'-----------------------------------------------------------------
Sub Main()
dim computer, vmName, itemName, itemValue, myVm, objArgs
set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")
computer = "."
set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")
set managementService = objWMIService.ExecQuery("select * from Msvm_VirtualSystemManagementService").ItemIndex(0)
set objArgs = WScript.Arguments
if WScript.Arguments.Count = 3 then
vmName = objArgs.Unnamed.Item(0)
itemName = objArgs.Unnamed.Item(1)
itemValue = objArgs.Unnamed.Item(2)
else
WScript.Echo "usage: cscript AddKvpItems.vbs vmName itemName itemValue"
WScript.Quit(1)
end if
set myVm = GetComputerSystem(vmName)
if AddKvpItems(myVm, itemName, itemValue) then
WriteLog "Done"
WScript.Quit(0)
else
WriteLog "AddKvpItems failed"
WScript.Quit(1)
end if
End Sub
'-----------------------------------------------------------------
' Retrieve Msvm_VirtualComputerSystem from base on its ElementName
'-----------------------------------------------------------------
Function GetComputerSystem(vmElementName)
On Error Resume Next
dim query
query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmElementName)
set GetComputerSystem = objWMIService.ExecQuery(query).ItemIndex(0)
if (Err.Number <> 0) then
WriteLog Format1("Err.Number: {0}", Err.Number)
WriteLog Format1("Err.Description:{0}",Err.Description)
WScript.Quit(1)
end if
End Function
'-----------------------------------------------------------------
' AddKvpItems
'-----------------------------------------------------------------
Function AddKvpItems(computerSystem, itemName, itemValue)
dim dataItem, dataItems, objInParam, objOutParams
AddKvpItems = false
set dataItem = objWMIService.Get("Msvm_KvpExchangeDataItem").SpawnInstance_()
dataItem.Data = itemValue
dataItem.Name = itemName
dataItem.Source = 0
dataItems = Array(1)
dataItems(0) = dataItem.GetText_(1)
set objInParam = managementService.Methods_("AddKvpItems").InParameters.SpawnInstance_()
objInParam.TargetSystem = computerSystem.Path_.Path
objInParam.dataItems = dataItems
set objOutParams = managementService.ExecMethod_("AddKvpItems", objInParam)
if objOutParams.ReturnValue = wmiStarted then
if (WMIJobCompleted(objOutParams)) then
AddKvpItems = true
end if
elseif (objOutParams.ReturnValue = wmiSuccessful) then
AddKvpItems = true
else
WriteLog Format1("AddKvpItem failed with error {0}", objOutParams.ReturnValue)
end if
End Function
'-----------------------------------------------------------------
' Handle wmi Job object
'-----------------------------------------------------------------
Function WMIJobCompleted(outParam)
dim WMIJob, jobState
WMIJobCompleted = true
set WMIJob = objWMIService.Get(outParam.Job)
jobState = WMIJob.JobState
while jobState = JobRunning or jobState = JobStarting
WriteLog Format1("In progress... {0}% completed.",WMIJob.PercentComplete)
WScript.Sleep(1000)
set WMIJob = objWMIService.Get(outParam.Job)
jobState = WMIJob.JobState
wend
if (WMIJob.JobState <> JobCompleted) then
WriteLog Format1("ErrorDescription:{0}", WMIJob.ErrorDescription)
WriteLog Format1("ErrorCode:{0}", WMIJob.ErrorCode)
WMIJobCompleted = false
end if
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
dim fileStream
set fileStream = fileSystem.OpenTextFile(".\AddKvpItems.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
Format2 = Format1(myString, arg0)
Format2 = Replace(Format2, "{1}", arg1)
End Function
'------------------------------------------------------------------------------
' The string formatting functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
Format1 = Replace(myString, "{0}", arg0)
End Function
Requirements
| Minimum supported client |
None supported |
| Minimum supported server |
Windows Server 2008 |
| End of client support |
None supported |
| End of server support |
Windows Server 2012 |
| Namespace |
Root\Virtualization |
| MOF |
|