VM Operations

  • Article

 

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.

<INSTANCE CLASSNAME="Msvm_VirtualSystemSettingData">

      <QUALIFIER NAME="dynamic" PROPAGATED="true" TYPE="boolean" TOSUBCLASS="false" TOINSTANCE="true">

          <VALUE>TRUE</VALUE>

      </QUALIFIER>

      <PROPERTY NAME="__PATH" CLASSORIGIN="___SYSTEM" TYPE="string">

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

      </PROPERTY>

      <PROPERTY NAME="__NAMESPACE" CLASSORIGIN="___SYSTEM" TYPE="string">

          <VALUE>root\virtualization</VALUE>

      </PROPERTY>

      <PROPERTY NAME="__SERVER" CLASSORIGIN="___SYSTEM" TYPE="string">

            <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 NAME="__PROPERTY_COUNT" CLASSORIGIN="___SYSTEM" TYPE="sint32">

           <VALUE>21</VALUE>

      </PROPERTY>

      <PROPERTY NAME="__RELPATH" CLASSORIGIN="___SYSTEM" TYPE="string">

 

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

Microsoft Synthetic Display Controller

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

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