VM Operations

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:

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:

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

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.

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:

This command will return the following content in myVirtualSystemSettingData.

For example:

Here is the result fragment from the command above.

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 http://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.

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.

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

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#:

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.

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:

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

ModifyVirtualSystem

DestroyVirtualSystem

Virtual System Management Services

Introduction

Msvm_VirtualSystemManagementService is a WMI object that Hyper-V uses to perform Virtual System Management related operations. The service codes are implemented in vmms.exe which is in %windows%\system32 directory. Hyper-V Manager UI also uses these WMI operations to perform VM management operations. I will briefly describe what these methods are designed for and map them against Hyper-V Manager UI. Hopefully this will help us to have a top level view of these methods.

There are 24 methods defined in VMMS. I will group them into the following 9 categories:

Categories	Methods
VM Operations	DefineVirtualSystem ModifyVirtualSystem DestroyVirutalSystem
VM Resource Operations	AddVirtualSystemResources ModifyVirtualSystemResources RemoveVirtualSystemResources
Import/Export	ExportVirtualSystem ImportVirtualSystem
Snapshots	CreateVirtualSystemSnapshot ApplyVirtualSystemSnapshot RemoveVirtualSystemSnaphot RemoveVirtualSystemSnaphotTree
Kvp Items	AddKvpItems ModifyKvpItems RemoveKvpItems
Service Settings	ModifyServiceSettings
VM Info	GetSummaryInformaiton GetVirtualSystemThumbnailImage
Unsupported Methods	RequestStateChange StartService StopService
Unimplemented Methods	CloneVirtualSystem PlanVirtualSystem InstantiateVirtualSystem

 

VM Operation

As the method names indicated, these three methods allow us to create, delete and modify a VM. Creating a VM is the first thing that we need to do when we working with Hyper-V. Destroy method will delete a VM that is no longer needed. Modify method will change the property values that are defined in Msvm_VirtualSystemSettingData and Msvm_VirtualSystemGlobalSettingData.

(Diagram 1)

VM Resource Operation

When a VM is created, certain virtual devices are added by default, such as virtual processor, virtual memory, virtual motherboard, virtual keyboard, etc. It’s just like when you purchase a physical bare bone machine; the system comes with CPU, motherboard, etc. There are additional components that you can add, remove and modify once a VM is created. The good news is that you don’t pay for them; but you need to understand these resource operation methods to manage them.

Most resource management related operations require the virtual machine in a stop state.  There are few exceptions, such as attaché an ISO image, remap network connection, etc.

From Hyper-V UI, these operations are performed through the Settings dialog box:

(Diagram 2)

Snapshots

One of benefits of a virtual machine is that it allows you to go back to a point of time in the past. The concept is difference from the Last Known Good in Windows. The Last Know Good can only bring the operating system back to a state that was working last time. It restores the operating system related system objects, such as Registry Key, system files, device configurations, etc.

We can snapshot a VM as long as it’s not in critical error state. By default, snapshot data are stored at: %systemdrive%\ProgramData\Microsoft\Windows\Hyper-V\Snapshots. The directory contains all the snapshots of this host machine.

(Diagram 3)

Import and Export

In the traditional physical machine world, it’s almost impossible to move an operating system on a physical machine A to a machine B. If machine A is having hardware issues, machine B needs to have a complete identical set of software to keep the business apps running.

With Hyper-V import and export, moving a virtual machine is as simple as mouse button clicks. Unlike snapshot, ExportVirtualSystem will make a copy of the entire virtual machine, include its snapshots. The export directory can be found at: %ExportDirectoryYouSpecified%\[VM ElementName].

In the following diagram 4, I specified my export directory as “C:\exports” for WinX64. My exported data was put into c:\exports\WinX64 directory.

(Diagram 4)

Kvp Items

Kvp exchange items allow the communications between the host and guests. AddKvpItems method will add a registry key pair into client registry at: HKEY_LOCAL_MACHINE\SOFTWARE\Micrsoft\Virtual Machine\External. The added registry key can only have REG_SZ type.

Guest can read the values that was added by the host and perform based on the actions that host has requested.

Guest can also add registry key values that can be retrieved by host from Msvm_KvpExchangeComponents object.

As you may have noticed, there are predefined values on guest HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Virtual Machine\Auto. “Getting the Virtual System DNS Name” sample on MSDN (http://msdn.microsoft.com/en-us/library/cc723870(VS.85).aspx) demonstrated how FullyQualifiedDomainName registry key value was retrieved from host.

Of course, the Kvp IC components need to be installed on the guest for the Kvp exchange items working properly.

These methods are not used by Hyper-V Manager UI.

Service Settings

ModifyServiceSettings method can modify the values that are defined in Msvm_VirtualSystemManagementSeviceSettingData. For example, we can call this method to change the default location for our Virtual Hard Disk; or we can change the default location of our VM configuration files.

(Diagram 5)

(Diagram 6)

VM Info

As method name indicated, GetSummaryInformation is a method that allows us to retrieve commonly used VM information with integer values. Otherwise, we have to traverse these information pieces that are stored in different objects by ourselves. It has much better performance than we query each object separately.

(Diagram 7)

One thing that you may be wondering, GetSummaryInformation already can retrieve the thumbnail image with the following values, why do we need GetVirtualSystemThumbnailImage method?

GetSummaryInformation only retrieve fix size Thumbnails. GetVirtualSystemThumbnailImage allow us to get a thumbnail image by specifying width and height. It becomes really handy if we want to get a full screen shot of a VM.

(Diagram 8)

Unsupported Methods

These methods were inherited from their ancestor schema definitions.  VMMS service can’t be started or stopped with StartService or StopService methods. VMMS service can only be started and stopped through Service Control Manager. For example, “net stop vmms”, “net start vmms” commands at DOS prompt with administrators privileges will stop and start VMMS service.

All these three methods will return 1 in their “ReturnValue”, which means “Unsupported Methods”.

Unimplemented Methods                       

These methods are defined in the Msvm_VirtualSystemManagementService, but there are no implementations for these methods. These probably are the optional methods from DMTF that don’t match with our product features.

Hyper-V WMI Introduction

It will be really difficult to under Hyper-V programming model without understanding WMI. I will briefly describe the WMI concepts that were used in our samples.

WMI borrowed Relational Database concept and applied to the object world. There are many similarities between Relational Database and WMI.

WMI CIM Studio is a visual tool that allows you to explore the WMI objects. The tool can be downloaded from:

http://www.microsoft.com/downloads/details.aspx?FamilyID=6430f853-1120-48db-8cc5-f2abdc3ed314&displaylang=en

Namespace

Virtualization is one of the WMI namespaces that defined on Windows 2008. From CIM Studio, we will see other namespaces as well. 

Just like programming against a backend SQL Server database, we can’t do anything else before we establish a connection to the database that we want to program against.

In WMI, we need to make such connection as well. Here is how we make connections to the Virtualization namespace:

VBScript

set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")

C#

ManagementScope scope = new ManagementScope(@"root\virtualization", null);

WMI Objects

Schema

As in SQL relational database, tables are defined with schema, WMI classes are also defined with schema. WMI also introduced inheritance concept in its class definition. Children class can inherent property and method defined in their parents.

For example, StartService and StopService methods are defined in CIM_Service class. They are also visible in Msvm_VirtualSystemManagementService, Msvm_ImageManagementService and Msvm_VirtualSystemManagementService classes. CIM classes are more like C# abstraction classes.

Hyper-V schema definition file can be found on your Hyper-V host machine at: %windir%\system32\WindowsVirtualization.mof.

Properties

Properties of WMI objects describe characteristics of WMI objects.  A property is a named value pair.

Type

Property value types are CIM typed. See the following link for a complete list of CIM types.

http://msdn.microsoft.com/en-us/library/aa386309(VS.85).aspx

Modification

It depends on each provider implementation, some providers implement Put method, which allows modifying object properties directly.

Most Hyper-V classes don’t support modifying properties directly. The following will not change the VM friendly name:

In the case above, we need to use “ModifyVirtualSystem” method modify VM name.  Here is the link to the MSDN sample code:

http://msdn.microsoft.com/en-us/library/cc136809(VS.85).aspx

Methods

Parameters

Methods that are defined with WMI objects takes [in] parameters and produce [out] parameters and a return value.

uint32 ModifyVirtualSystem

(

[in]   CIM_ComputerSystem REF ComputerSystem,

[in]   string SystemSettingData,

[out]  CIM_VirtualSystemSettingData REF ModifiedSettingData,

[out]  CIM_ConcreteJob REF Job

);

ModifyVirtualSystem method takes following parameters as inputs:

1.       Object path that is pointing to CIM_ComputerSystem object.

2.       Msvm_VirtualSystemSettingData that is in a Unicode string in Xml format.

Output parameters:

1.       ModifiedSettingData contains a path in Unicode string that is pointing to an CIM_VirtualSystemSettingData

2.       Job contains a path in Unicode string that is pointing to CIM_ConcreteJob object

The method is an unsynchronized operation.  The Job object in the output is used for pulling operation complete state.

The return value uint32 is returned in “RetureValue” of method out parameter. The return value indicates if the method was executed successfully.

Operation Impacts

An execution a WMI method may have impacts on computer system resources. It really depends on provides’ implementation.  

When we call methods that are defined in Msvm_ImageManagementService object, we will interact with host file system to perform Virtual Hard Disk file operations. When we call the methods that are defined in Msvm_VirtualSwitchManagementService, we will interact with the host networking stack to performance network configuration activities, etc.

The detail impacts of Hyper-V methods will be posted when we discuss each individual method.

Relationships

query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmElementName)

select * from Msvm_SyntheticEthernetPortSettingData where InstanceID like '%default'

query = Format1("ASSOCIATORS OF {{0}} WHERE resultClass = Msvm_AllocationCapabilities", poolResource.Path_.Path)

ManagementObjectCollection allocationCapabilities = poolResource.GetRelated("Msvm_AllocationCapabilities");

query = Format1("REFERENCES  OF {{0}} WHERE resultClass = Msvm_SettingsDefineCapabilities", capbility.Path_.Path)

ManagementObjectCollection settingDatas = allocationCapability.GetRelationships("Msvm_SettingsDefineCapabilities");

Events

Option Explicit

dim fileSystem

dim objWMIService

Main()

'-------------------------------------------------

' The Main

'-------------------------------------------------

Sub Main()

    dim objArgs, computer, eventQuery, wmiSink

    set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")

    computer = "."

    set objWMIService = GetObject("winmgmts:\\" & computer & "\root\virtualization")

    eventQuery = "Select * from __instancecreationevent within 10"

    Set wmiSink = WScript.CreateObject("WbemScripting.SWbemSink", "SINK_")

    objWMIService.ExecNotificationQueryAsync wmiSink, eventQuery

    WriteLog "Listening for the WMI events..."

     While(True)

        Wscript.Sleep(1000)

    Wend

 End Sub

 '-------------------------------------------------

' Sink call back function

'-------------------------------------------------

Sub SINK_OnObjectReady(wmiObject, wmiAsyncContext)

    dim p

    for each p in wmiObject.Properties_

        if p.Name = "TargetInstance" then

            WriteLog p.Value.Path_.RelPath

        end if

    next

End Sub

 '-----------------------------------------------------------------

' Create the console log files.

'-----------------------------------------------------------------

Sub WriteLog(line)

    Dim fileStream

    Set fileStream = fileSystem.OpenTextFile("WMIEvent.log", 8, true, -1)

    WScript.Echo line

    fileStream.WriteLine line

    fileStream.Close

End Sub

Build and Run C# Samples

To build and run each sample in C#, here are the steps:

1. Create a new project:

2. Add a new class and name it as common.cs:

 

3. Copy the common library code from:  http://msdn.microsoft.com/en-us/library/cc723869(VS.85).aspx and paste it into common.cs

4. Copy the C# sample and paste it into program.cs, for example: http://msdn.microsoft.com/en-us/library/cc723870(VS.85).aspx

5. Add System.Management as reference:

That is it. The sample project is ready to run.

Cheers,

Howard.

Debug Hyper-V VBSCript Samples

One of customers was not able to get the DNS name from a VM by running the samples at: http://msdn.microsoft.com/en-us/library/cc723870(VS.85).aspx

I debugged and found out that the Win2008 Virtual System was still running Hyper-V beta. Here are the steps that I took:

1. Copied the VBScript from the MSDN website above.
2. Saved the VBScript as GetVirtualSystemDNSName.vbs
3. Ran following command: cscript /X GetVirtualSystemDNSName.vbs vmName
4. Selected "New Instance of Visual Studio" as "Just in time debugger"
5. Set break point at line 97 as shown in the picture below.

When I watched the values that was returned in the exchange items, the exchange item "Name" was "Fqdn". In the sample code, we tried to find Virtual System FullyQualifiedDomainName Kvp exchange item by running following XPath query:

xpath = "/INSTANCE/PROPERTY[@NAME='Name']/VALUE[child:text() = 'FullyQualifiedDomainName']"

The query returned empty node set sicne "Fqdn" != "FullyQualifiedDomainName".  

Fqdn was renamed to FullyQualifiedDomainName after Hyper-V beta.

In the debug watch window, there are other Kvp exchange items. By exploring the their contents from watch window, you will find that this sample code can be modified to retrive other Kvp items.

Cheers,

Howard. 

Blog Introduction

I wrote the msdn Hyper-V documentation samples with my colleges' help. I want to use this blog to explain the contexts that we missed from these samples.

I will be really happy if we can achieve the following goals together:

1. Make our MSDN online samples easier to understand.
2. Get your feedbacks into these samples.
3. Get scenario samples that we need to write.

So far we have 48 samples written in both C# and VBScripts. It covers most the API that Hyper-V currently has. These samples can be divided into the following categories:

1. Virtual System Management Service. 17 methods.  http://msdn.microsoft.com/en-us/library/cc136940(VS.85).aspx
2. Virtual Switch Management Service. 13 methods.  http://msdn.microsoft.com/en-us/library/cc136938(VS.85).aspx
3. Virtual Image Management Service. 13 methods. http://msdn.microsoft.com/en-us/library/cc136845(VS.85).aspx
4. Keyboard and Mouse. 3 methods. http://msdn.microsoft.com/en-us/library/cc136956(VS.85).aspx. http://msdn.microsoft.com/en-us/library/cc136772(VS.85).aspx
5. Msvm_ComputerSystem. 1 method. http://msdn.microsoft.com/en-us/library/cc723874(VS.85).aspx
6. Scenarios. 1 Scenario  http://msdn.microsoft.com/en-us/library/cc723870(VS.85).aspx

I will try to explain these APIs in the following context:

1. Methods and VM relationships 
2. WMI objects it creates.
3. Mapping between the Hyper-V console UI and the method

I am looking forward getting your feedbacks. 

Cheers,

Howard.