Hyper-V Programming Model

VM Operations

HowardHao — Tue, 21 Jul 2009 01:18:00 GMT

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:

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

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:

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

ModifyVirtualSystem

DestroyVirtualSystem

Virtual System Management Services

HowardHao — Thu, 28 Aug 2008 20:40:00 GMT

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?

Small Thumbnail Image (80x60)	5
Medium Thumbnail Image (160x120)	6
Large Thumbnail Image (320x240)	7

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

HowardHao — Sat, 23 Aug 2008 01:11:00 GMT

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.

(Diagram 1)

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:

computer = "."

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

set computer= objWMIService.ExecQuery("SELECT * FROM Msvm_ComputerSystem where ElementName='Win2008'").ItemIndex(0)

computer.ElementName = "My Computer"

computer.Put_

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

In relational database, we construct table relationships with primary keys and foreign keys. In the many to many relationships, we create a link table as the diagram shows.

(Diagram 2)

The relationships help us to retrieve related information in table2 from table1.

In WMI, we use the similar concept to build object trees. In between two objects, we use a association object to link them up. The main purpose of this association object is to help us to navigate from one object to other. It’s all about how to retrieve information that was structured in object world.

(Diagram 3)

Here is an association object when we view it from WMI CIM Studio:

(Diagram 4)

Object Path

In Relational data base, primary keys uniquely identify an entity (table row). In WMI, an object path is the unique identifiers for each object. An object path consists of object schema path (WMI class path) and key instance values.

WMI Class Path

Key Value

\\MyMachine\root\virtualization:Msvm_SettingsDefineState.

ManagedElement="\\MyMachine\root\virtualization:Msvm_ComputerSystem.CreationClassName="Msvm_ComputerSystem\",Name=\"A2E571D2-6237-460C-8413-CB246C55E029",

SettingData="\\MyMachine\root\virtualization:Msvm_VirtualSystemSettingData.InstanceID="Microsoft:A2E571D2-6237-460C-8413-CB246C55E029"

Queries

WQL is a subset of SQL. For complete reference, please visit:

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

The queries that we used in our samples are

· Simple select statement

· WMI ASSOCIATORS OF

· WMI REFERENCES OF

Select Statement

As you might have noticed, we use the select statement in AddVirtualSystemResources (http://msdn.microsoft.com/en-us/library/cc160705(VS.85).aspx)

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

But when we query Msvm_SyntheticEthernetPortSettingData default definition object, we traversed the following objects by using ASSOCIATORS and REFERENCES queries.

(Diagram 5)

You might wonder I can use the following shortcut to get it working, why bother with the object traversing:

select * from Msvm_SyntheticEthernetPortSettingData where InstanceID like '%default'

Yes, you could retrieve the Msvm_SyntheticEthernetPortSettingData definition object this way, but it’s not recommended.

ASSOCIATORS OF

ASSOCIATORS OF is one of the two special queries was not part of the ANSI SQL queries.

As you can see the (Diagram 2) above, this query allows us to retrieve object2 from object1 based on their associations.

In AddVirtualSystemResources VBScript sample, we use following query to get Msvm_AllocationCapabilities object.

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

poolResource.Path_.Path points to Synthetic Ethernet object instance that is defined in Msvm_ResourcePool. As you can see in (Diagram 5), we will get Msvm_AllocationCapabilities object after this query.

C# System.Management assembly introduced a wrapper (Syntax sugar) around this query. In our sample code at http://msdn.microsoft.com/en-us/library/cc723869(VS.85).aspx, we query Msvm_AllocationCapabilities as following:

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

REFERENCES OF

In (Diagram 2) above, REFERENCES OF will bring us to the Association object.

In AddVirtualSystemResources VBScript sample, we use following query to get Msvm_SettingsDefineCapabilities object.

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

The reason for us to get Msvm_SettingsDefineCapabilities because ValueRole(or ValueRange) property that is defined in this association class:

ValueRole	ValueRange	Associated with Msvm_SyntheticEthernetPortSettingData
0(Point)	0(Default)	Microsoft:Definition\6A45335D-4C3A-44B7-B61F-C9808BBDF8ED\Default
3(Supported)	1(Minimum)	Microsoft:Definition\6A45335D-4C3A-44B7-B61F-C9808BBDF8ED\Minimum
3(Supported)	2(Maximum)	Microsoft:Definition\6A45335D-4C3A-44B7-B61F-C9808BBDF8ED\Maximum
3(Supported)	3(Increment)	Microsoft:Definition\\6A45335D-4C3A-44B7-B61F-C9808BBDF8ED\\Increment

Please also reference to MSDN REMARK section at http://msdn.microsoft.com/en-us/library/cc136891(VS.85).aspx for meaning of these values.

Once we find Msvm_SettingsDefineCapabilities with ValueRole = 0 or Value Range = 0, then we find Msvm_SyntheticEthernetPortSettingData default object instance.

This is a second query that C# System.Management assembly has an API wrapper. In our sample code at http://msdn.microsoft.com/en-us/library/cc723869(VS.85).aspx, here is how we retrieve Msvm_SettingsDefineCapabilities object:

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

Events

A WMI event is fired when a WMI object state changed. Hyper-V WMI provider creates a __InstanceOperationEvent object when a Hyper-V object state changed. In the following dialog from CIM Studio, it shows four different kinds of events maybe generated.

Most Hyper-V operations are synchronized operations. Most of these methods provide a Job object allow you to pull the operation status in a while loop. We can also monitor operation status by listening object instance creation events; but it’s trickier since an operation may create many events.

The following VBScript sample codes will allow us monitor all Hyper-V WMI object creation events. The program will display WMI object relative path for each object that is created.

To run the program, simply copy the following codes and save it as eventmon.vbs; then run it from command line prompt as: cscript eventmon.vbs

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

Here is a sample output when creating a new VM from Hyper-V Manager Console:

WMI and Relational Database Comparison

	WMI	Relational Database
Schema	Classes	Tables
	Properties	Columns
	Keys	Primary Keys
	Keys	Foreign Keys
	Path	Three part names. machineName.databaseName.tablename
	Child class inherits the ancestor’s properties and methods.	Relational database doesn’t have inheritance concept.
Object Entities	Instances of the class	Rows
Relationships	Association	The other table in M:M relationships
Relationships	References	The linked table in M:M relationships
Query Language	WQL	SQL
	ASSOCIATOR	Join
	REFERENCES	Join
Function Executions	Methods	Store Proc, .Net functions
Data Types	CIM data types	SQL data types
Meta Info	WMI uses classes to define objects. Classes are schema information about the WMI.	SQL system tables defines the entire database objects

Hyper-V Object Properties can be Modified with Put

Class	Property
Msvm_VirtualSwitch	ElementName
Msvm_VirtualSwitch	ScopeOfResidence

Msvm_SwitchPort.	ElementName
	ScopeOfResidence
	VMQOffloadWeight
	ChimneyOffloadWeight
	AllowMacSpoofing

Msvm_InternalEthernetPort	ElementName

Msvm_VLANEndpointSettingData	AccessVLAN
	NativeVLAN
	PruneEligibleVLANList
	TrunkedVLANList

Msvm_VLANEndpoint	DesiredEndpointMode

DMTF

Virtualization schema is an industry wide collaboration efforts, here are DMTF’s standard if you are interested:

DSP1042, System Virtualization Profile
DSP1057, Virtual System Profile
DSP1059, Generic Device Resource Virtualization Profile
DSP1041, Resource Allocation Profile
DSP1043, Allocation Capabilities Profile

Build and Run C# Samples

HowardHao — Thu, 21 Aug 2008 19:27:00 GMT

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

HowardHao — Tue, 19 Aug 2008 22:56:00 GMT

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:

Copied the VBScript from the MSDN website above.
Saved the VBScript as GetVirtualSystemDNSName.vbs
Ran following command: cscript /X GetVirtualSystemDNSName.vbs vmName
Selected "New Instance of Visual Studio" as "Just in time debugger"
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

HowardHao — Tue, 19 Aug 2008 01:47:00 GMT

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:

Make our MSDN online samples easier to understand.
Get your feedbacks into these samples.
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:

Virtual System Management Service. 17 methods. http://msdn.microsoft.com/en-us/library/cc136940(VS.85).aspx
Virtual Switch Management Service. 13 methods. http://msdn.microsoft.com/en-us/library/cc136938(VS.85).aspx
Virtual Image Management Service. 13 methods. http://msdn.microsoft.com/en-us/library/cc136845(VS.85).aspx
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
Msvm_ComputerSystem. 1 method. http://msdn.microsoft.com/en-us/library/cc723874(VS.85).aspx
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:

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

I am looking forward getting your feedbacks.

Cheers,

Howard.

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