I just find out that some WMI calls are not documented in the MSDN library for Hyper-V. Apparently there are three methods in MSvm_VirtualSystemManagementService to create a new virtual machine and only one of them is explained.

• DefineVirtualSystem : Method used to create a computer system
• PlanVirtualSystem
• InstantiateVirtualSystem

I know that the documentation is still in early beta phase and appreciate all effort of Microsoft for publishing it. Even with the current state of the materials, there is a lot of things you can do with WMI against Hyper-V

So Enjoy!

/Dung

The Msvm_VirtualSystemManagementService Class

Today I discuss about the Msvm_VirtualSystemManagementService Class. The Msvm_VirtualSystemManagementService class represents the virtualization service running on the host system. Using this class, you can control the creation, modification, deletion, import and export of virtual systems. You can also create snapshots and apply them to virtual systems. All those operations are exposed as methods of the Msvm_VirtualSystemManagementService class.

Creating snapshots of virtual systems

A snapshot is a point-in-time image of a virtual system. It can be seen as a quick way to backup a virtual machine. You can take a snapshot at any time with any guest operating system and can restore a virtual a machine at any stage.

Let see some examples of WMI class to create and apply snapshots.

First you connect to the virtualization service.

PS C:\> $VSService = get-wmiobject –namespace root\virtualization –class Msvm_VirtualSystemManagementService

Use get-member to discover all the methods exposed by this object

PS C:\> $VSService | get-member | where {$_.Membertype -match 'Method'}

Name                            MemberType   Definition
----                            ----------   ----------
AddKvpItems                     Method       System.Management.ManagementBas...
AddVirtualSystemResources       Method       System.Management.ManagementBas...
ApplyVirtualSystemSnapshot      Method       System.Management.ManagementBas...
CloneVirtualSystem              Method       System.Management.ManagementBas...
CreateVirtualSystemSnapshot     Method       System.Management.ManagementBas...
DefineVirtualSystem             Method       System.Management.ManagementBas...
DestroyVirtualSystem            Method       System.Management.ManagementBas...
ExportVirtualSystem             Method       System.Management.ManagementBas...
GetSummaryInformation           Method       System.Management.ManagementBas...
GetVirtualSystemThumbnailImage  Method       System.Management.ManagementBas...
ImportVirtualSystem             Method       System.Management.ManagementBas...
InstantiateVirtualSystem        Method       System.Management.ManagementBas...
ModifyKvpItems                  Method       System.Management.ManagementBas...
ModifyServiceSettings           Method       System.Management.ManagementBas...
ModifyVirtualSystem             Method       System.Management.ManagementBas...
ModifyVirtualSystemResources    Method       System.Management.ManagementBas...
PlanVirtualSystem               Method       System.Management.ManagementBas...
RemoveKvpItems                  Method       System.Management.ManagementBas...
RemoveVirtualSystemResources    Method       System.Management.ManagementBas...
RemoveVirtualSystemSnapshot     Method       System.Management.ManagementBas...
RemoveVirtualSystemSnapshotTree Method       System.Management.ManagementBas...
RequestStateChange              Method       System.Management.ManagementBas...

So you can see that it has some interesting methods!
To create a snapshot, you first identify the virtual system, get its absolute path and use it as a parameter to call CreateVirtualSystemSanpshot.

Using the lab environment I describe here, let consider the IIS-Core virtual system.

PS C:\> $Core = get-wmiobject -namespace root\virtualization -class Msvm_ComputerSystem -filter " ElementName = 'IIS-CORE' "

PS C:\> $VSService.CreateVirtualSystemSnapShot($Core.__PATH)

The call should return 0 or 4096. If not, it means that there is an error in the call.

Finding snapshots of virtual systems

Once a snapshot is taken, its configuration is stored as an instance of the Msvm_VirtualSystemSettingData object. The Msvm_VirtualSystemSetting class is used to represent all virtualization-specific settings for a virtual system which can be either a virtual machine or a snapshot.  A WMI query on this class will return settings of virtual machines and snapshots that currently exist on the host system. To distinguish snapshot from virtual machine, you should filter the query on the property called SettingType. This property can have one of the two values:

• SettingType = 3. The instance contains settings of a virtual machine
• SettingType = 5.. The instance contains settings of a snapshot

PS C:\> $VSService = get-wmiobject –namespace root\virtualization –class Msvm_VirtualSystemSettingData -filter "SettingType = 5"

Now that you get a list of snapshots with their settings, how can you find the linkage between snapshots and virtual machine? As you know, a virtual machine can have zero snapshot or several snapshots taken at different points in time. A query to Msvm_VirtualSystemSettingData with a filter on SettingType returns a list of snapshots in the order they are created and they are not sorted per virtual machine!
Fortunately, you can use the Property called SystemName of the Msvm_VirtualSystemSettingData class to identify the associated virtual system. This property contains the object GUID of a virtual machine. This is the same GUID that you find on the Name property of the Msvm_ComputerSystem class. You make a WMI query on the Msvm_ComputerSystem class to get a list of virtual systems that exist on a host. See the discussion of this class here.

With this information, you can now find all snapshots that are associated to a virtual machine.

PS C:\> get-wmiobject -namespace root\virtualization -class Msvm_VirtualSystemData -filter "SystemName=`'$($Core.Name)`' and SettingType = 5”

Applying snapshots to a virtual system

You can apply a snapshot to a virtual machine to restore the system to a state at the time the snapshot was taken. You don't need to apply snapshots in a particular order but can take any snapshot associated to this machine and restore it.
You use the method called ApplyVirtualSystemSnapshot  of the Msvm_VirtualSystemManagementService class to perform the restore operation form a command line. Here is the code:

PS C:\> # Let's assume that you have identified a particular snapshot using the example above and store the object in a variable
PS C:\> # called $ASnapShot

PS C:\> # First you need to sop the virtual machine.
PS C:\> $Core.RequestStateChange(3)

PS C:\> # Then apply a snapshot
PS C:\> $VSService.ApplyVirtualSystemSnapShot($Core.__PATH, $ASnapShot.__PATH)
 

From the Hyper-V Manager console, you will notice that the "restored" virtual system will be put in 'Saved' state mode. Starting it will restore the machine to its state before the snapshot was taken. 

Summary

This entry provides examples of creating, finding and applying a snapshot on a virtual machine using the Hyper-V WMI classes.

Until the next time....
Hope you enjoy it!

/Dung

HyperV WMI PowerShell