VM Operations

Artikel
07/20/2009

There are three operation methods regarding VM operations:

1. DefineVirtualSystem

2. ModifyVirtualSystem

3. DestroyVirtualSystem

VMs are represented by in memory WMI objects and serialized as Xml files as their backend storage. DefineVirtualSystem creates WMI objects and Xml files that are representing the creation VM. DestroyVirtualSystem will delete the WMI objects and its Xml file storage. ModifyVirtualSystem modifies attributes that are related to the VM basic attributes.

DefineVirtualSystem

Here is the definition of the API:

uint32 DefineVirtualSystem(

[in] string SystemSettingData,

[in] string ResourceSettingData[],

[in] CIM_VirtualSystemSettingData REF SourceSetting,

[out] CIM_ComputerSystem REF DefinedSystem,

[out] CIM_ConcreteJob REF Job

);

What’s this API? Is a Window’s API or .Net API? The answer is a WMI API. This API contains most common data types used in Hyper-V APIs. [in] indicates the parameter will be parsed by WMI providers. [out] indicates the return values will be returned from the named properties.

REF indicates the parameter value contains WMI object path.

SystemSettingData

Language Aspect

1. CIM_String

The string type of SystemSettingData is a CIM_String type. Based on DMTF spec definition, the CIM_String is defined as:

https://www.dmtf.org/standards/published_documents/DSP201.html/#SecVALUEELEMENTS

If the CIM type is string, then the PCDATA value MUST be a sequence of zero or more UCS-2 characters.

As you have noticed, the current C#, VBScript, Jscript, PowerShell, etc, all their string types are also defined as UCS-2 types. There is no need for WMI providers to do type conversions.

2. CIM_String Content

What does this Unicode string value contain? Based on MSDN documentation, SystemSettingData should contain an instance value of Msvm_VirtualSystemSettingData or Msvm_GlobalSystemSetingData. There are three formats that you can pass in. Here are the C# enum values for these three formats.

// Summary:

// Describes the possible text formats that can be used with System.Management.ManagementBaseObject.GetText(System.Management.TextFormat).

public enum TextFormat

{

// Summary:

// Managed Object Format

Mof = 0,

// Summary:

// XML DTD that corresponds to CIM DTD version 2.0.

CimDtd20 = 1,

// Summary:

// XML WMI DTD that corresponds to CIM DTD version 2.0. Using this value enables

// a few WMI-specific extensions, like embedded objects.

WmiDtd20 = 2,

}

We are lucky that we don’t have to hand craft these contents. There is a GetText method on all WMI objects, once we get object instance, we can simply call this API to get the object instance string value.

For example:

String myVirtualSystemSettingData = myVirtualSystemSettingInstance.GetText(TextFormat.Mof);

This command will return the following content in myVirtualSystemSettingData.

instance of Msvm_VirtualSystemSettingData

{

BaseBoardSerialNumber = "1084-4227-5968-1650-2832-6382-65";

BIOSGUID = "{7D623876-DCC7-4B17-88CD-20F7C4DFC981}";

BIOSNumLock = FALSE;

BIOSSerialNumber = "1084-4227-5968-1650-2832-6382-65";

BootOrder = {1, 2, 3, 0};

Caption = "Virtual Machine Settings";

ChassisAssetTag = "6141-4608-6059-5256-9166-9270-26";

ChassisSerialNumber = "1084-4227-5968-1650-2832-6382-65";

CreationTime = "20090715003340.902692-000";

Description = "Active settings for the virtual machine.";

ElementName = "My First VM";

InstanceID = "Microsoft:7BC51D88-76E1-4C4F-BA74-CD4F530475E3";

Notes = "";

NumaNodeList = {};

NumaNodesAreRequired = FALSE;

Parent = NULL;

SettingType = 3;

SystemName = "7BC51D88-76E1-4C4F-BA74-CD4F530475E3";

VirtualSystemType = 301;

};

For example:

String myVirtualSystemSettingData = myVirtualSystemSettingInstance.GetText(TextFormat.WmiDtd20);

Here is the result fragment from the command above.

</QUALIFIER>

<VALUE>\\HHAOCT2\root\virtualization:Msvm_VirtualSystemSettingData.InstanceID="Microsoft:7BC51D88-76E1-4C4F-BA74-CD4F530475E3"</VALUE>

</PROPERTY>

<VALUE>root\virtualization</VALUE>

</PROPERTY>

<VALUE>HHAOCT2</VALUE>

</PROPERTY>

<PROPERTY.ARRAY NAME="__DERIVATION" CLASSORIGIN="___SYSTEM" TYPE="string">

<VALUE.ARRAY>

<VALUE>CIM_VirtualSystemSettingData</VALUE>

<VALUE>CIM_SettingData</VALUE>

<VALUE>CIM_ManagedElement</VALUE>

</VALUE.ARRAY>

</PROPERTY.ARRAY>

</PROPERTY>

Design purpose:

This parameter allows you to give proper names of your VMs, device boot sequences, etc.

ResourceSettingData[]

Language Aspect:

Wow, WMI string array. How do I translate that into the programming language that I am using? Actually it’s really straight forward; it just maps into your programming language array types. Based on MSDN documentation https://msdn.microsoft.com/en-us/library/cc136786(VS.85).aspx, resource setting is defined as CIM_ResourceAllocationSettingData. Here are the inheritance concrete classes:

Any data instance values in an array from these derived classes are valid language data types.

Here are the resources are part of default system, they can’t be added or removed. The IC components are available only when the ICs are installed inside of an VM.

Resource Type	Resource SubType	Other ResourceType	Resource Setting Data class	Come with default system
Other = 1		Microsoft Virtual Diskette Controller	Msvm_ResourceAllocationSettingData	Yes
		Microsoft Shutdown Component	Msvm_ShutdownComponentSettingData	Once the ICs are installed
		Microsoft Time Synchronization Component	Msvm_TimeSyncComponentSettingData	Once the ICs are installed
		Microsoft Key-Value Pair Exchange Component	Msvm_KvpExchangeComponentSettingData	Once the ICs are installed
		Microsoft Heartbeat Component	Msvm_HeartBeatComponentSettingData	Once the ICs are installed
		Microsoft VSS Component	Msvm_VssComponentSettingData	Once the ICs are installed
Processor = 3	Microsoft Processor		Msvm_ProcessorSettingData	Yes
Memory = 4	Microsoft Virtual Machine Memory		Msvm_MemorySettingData	Yes
IDEController = 5	Microsoft Emulated IDE Controller		Msvm_ResourceAllocationSettingData	Yes
IODevice = 13	Microsoft Synthetic Mouse		Msvm_ResourceAllocationSettingData	Once the ICs are installed
	Microsoft Virtual PS2 Mouse			Yes
	Microsoft Virtual Keyboard			Yes
	Microsoft Serial Controller			Yes
FloppyDrive = 14	Microsoft Synthetic Diskette Drive		Msvm_ResourceAllocationSettingData	Yes
Serialport = 17	Microsoft Serial Port		Msvm_ResourceAllocationSettingData	Yes
Graphics Controller = 20	Microsoft S3 Display Controller		Msvm_ResourceAllocationSettingData	Yes
Graphics Controller = 20	Microsoft Synthetic Display Controller		Msvm_ResourceAllocationSettingData	Once the ICs are installed

The following resources can be added or removed. But only top level devices can be used in the ResourceSettingData parameter; which are ParaallelSCSIHBA and two EthernetAdapter cards. For a lower level device to exist, the higher level device must be existed already. For example, a “Microsoft Synthetic DVD Drive” can’t exist without a “Microsoft Emulated IDE Controller” or a “Microsoft Synthetic SCSI Controller”. These lower level devices can’t be part of these resource arrays.

To add the lower level devices, AddVirtualSystemResource should be the method of choice.

Resource Type	Resource SubType	Resource Setting Data class
ParallelSCSIHBA = 6	Microsoft Synthetic SCSI Controller	Msvm_ResourceAllocationSettingData
EthernetAdapter = 10	Microsoft Synthetic Ethernet Port	Msvm_SyntheticEthernetPortSettingData
EthernetAdapter = 10	Microsoft Emulated Ethernet Port	Msvm_EmulatedEthernetPortSettingData
DVDdrive = 16	Microsoft Synthetic DVD Drive	Msvm_ResourceAllocationSettingData
StorageExtent = 21	Microsoft Virtual Hard Disk	Msvm_ResourceAllocationSettingData
	Microsoft Virtual CD/DVD Disk
	Microsoft Virtual Floppy Disk
Disk = 22	Microsoft Synthetic Disk Drive	Msvm_ResourceAllocationSettingData

Here are additional virtual resources that were defined in the DMTF spec, but currently are not supported by the Hyper-V.

Resource Type

ComputerSystem = 2

FCHBA = 7

iSCSIHBA = 8

IBHCA = 9

OtherNetworkAdapter = 11

IOSlot = 12

CDDrive = 15

Parallelport = 18

USBController = 19

Tape = 23

OtherStorageDevice = 24

FirewireController = 25

PartitionableUnit = 26

BasePartitionableUnit = 27

PowerSupply = 28

CoolingDevice = 29

SourceSetting

Language Aspect:

This is a ref type parameter. As I have mentioned in the introduction posts, a reference type is an object path. SourceSetting should be a path that is pointing to CIM_VirtualSystemSettingData derived classes, which are Msvm_VirtualSystemSettingData or Msvm_GlobalSystemSetingData.

Design purpose:

It’s a little bit confusing that there is a SystemSettingData parameter which takes instance of Msvm_VirtualSystemSettingData or Msvm_GlobalSystemSetingData. Now there is a ResourceSetting parameter uses ref type that pointed to the same WMI classes; this parameter is used to clone an existing system resources. For example, if you have an existing VM, you want to create a new VM which has same resource configurations, and then you can pass in path that is point to this VM’s Msvm_VirtualSystemSettingData data instance.

DefinedSystem

Language Aspect:

It’s a ref type out parameter. It contains the path to the new created VM. Here is how to contract the object in C#:

ManagementObject definedSystem = new ManagementObject(outParams["DefinedSystem"].ToString());

Design purpose:

It provides an instance access to the new created VM. VM operations can be performed on the instance. For example, the following code will power on the new VM.

ManagementObject definedSystem = new ManagementObject(outParams["DefinedSystem"].ToString());

ManagementBaseObject inParams = definedSystem.GetMethodParameters(“RequestStateChange”);

inParams["RequestedState"] = 2;

ManagementBaseObject outParams = definedSystem.InvokeMethod(Msvm_ComputerSystem.Method.RequestStateChange, inParams, null);

Job

Language Aspect:

There are three concrete classes derived from CIM_ConcreteJob. The return value in this parameter is an object path points to an Msvm_ConcreteJob object instance.

Design purpose:

This object provides a synchronization mechanism of Hyper-V API operations. We can pull the status of the object to see if an operation has been completed or not. For sample codes, please check out JobCompleted that is defined at:

https://msdn.microsoft.com/en-us/library/cc723869(VS.85).aspx

ModifyVirtualSystem

DestroyVirtualSystem

Comments

Anonymous
February 01, 2010
how to set default memory size ? ManagementPath settingPath = new ManagementPath("Msvm_MemorySettingData"); ManagementClass memoryResourceSettingClass = new ManagementClass(scope, settingPath, null); ManagementObject memoryResourceSettingData = memoryResourceSettingClass.CreateInstance(); memoryResourceSettingData["VirtualQuantity"] = memory; string settingData = memoryResourceSettingData.GetText(TextFormat.CimDtd20); but exception is parameter error.

Freigeben über

VM Operations

DefineVirtualSystem

SystemSettingData

Language Aspect

1. CIM_String

2. CIM_String Content

Design purpose:

ResourceSettingData[]

Language Aspect:

SourceSetting

Language Aspect:

Design purpose:

DefinedSystem

Language Aspect:

Design purpose:

Job

Language Aspect:

Design purpose:

ModifyVirtualSystem

DestroyVirtualSystem

Comments

Zusätzliche Ressourcen