Microsoft announced last week the Hyper-V WMI provider and published its documentation here. I find it very interesting for IT Pros like us to build scripts to manage and provision virtual machines through WMI. When combining PowerShell with WMI, you really have powerful tools in your hands for managing virtual environments.

Let's take a look at the Hyper-V WMI provider through some examples.

First you need a minimal environment to work with :=).

1. You must have at least an x64 box that supports Hardware Assisted Virtualisation (HAV), meaning that the CPU must have Intel-VT or AMD-V enabled for Hyper-V.
2. You install Windows Server 2008 RC1 with Hyper-V Beta OS on this box
3. You install the Hyper-V Server Role and Windows PowerShell feature using Server Manager
4. You use the Hyper-V Manager console to create some virtual machines.

Note: You don't need to install any OS for guest systems, the examples below require some guests running ( even with no OS) to play with WMI.

Here is a screenshot of my lab environment

Exploring the namespace

All the examples below use Windows PowerShell as scripting language. PowerShell is the next generation of interactive shell from Microsoft. It's very powerful as it is an object-based shell, meaning that all input/output from PowerShell are objects and not text. IT administrators can leverage all objects model (WMI-COM-.NET) exposed by the OS and use them with PowerShell. Today, Windows PowerShell is shipped with Windows Server 2008 and there is a release of PowerShell on the Microsoft web site. Go and take a look at it here: www.microsoft.com/PowerShell 

Enough marketing for PowerShell =) Let's do some work now!

First, open a Windows PowerShell window.
You then need to find the namespace for the Hyper-V WMI provider. For that, use this command:

PS C:\> get-wmiobject -namespace root -class __NAMESPACE | select Name      
Name
-------
subscription
DEFAULT
CIM V2
.......
Virtualization
-----

Note: There are two(2) underscore (_) characters before NAMESPACE

So the namespace for the Hyper-V WMI provider is root\virtualization. So far so good! Let's find all the classes exposed through this WMI provider

PS C:\> get-wmiobject -namespace root\virtualization -list

This command returns all classes that exist under this namespace and you will notice that there are hundreds of them! Their names start with CIM_ or Msvm_. CIM classes provide information about system in general (based on DMTF standard) and Msvm classes are more specific to Windows Virtualization environment.
Let's take a look at some of them. As a matter of fact, you can get detailed documentation of Msvm classes here.

The Msvm_ComputerSystem Class

As its name implies, the Msvm_ComputerSystem class contains information about a system which is either a host system or a virtual system (or virtual machine -VM). Use this class as follow:

PS C:\> get-wmiobject -namespace root\virtualization -class Msvm_ComputerSystem

This command returns all instances of Msvm_ComputerSystem, each object represents a virtual system or a host system. The output produces a lot of information as the class has several properties. By the way if you want to find out all properties of the class, simply pipe the previous command to get-member.  Find properties that are of your interest  and filter the output of the previous command to find useful information. In the following example, I will focus on those properties:  ElementName , Name and Caption or Description.

The ElementName attribute is set to the display name of a virtual machine or the NETBIOS name of the host system. The Name attribute contains a GUID of the computer object if the computer is a virtual machine. When the Name contains a “real” name, the corresponding object describes a host system. The Description or Caption attribute can also give some hint about the type of the computer.

In my environment, the output of this command shows that the host system is named VIRIDIAN and is hosting 4 virtual systems

To find out all virtual systems on a given host, you can filter the output of the previous command as follow:

PS C:\> get-wmiobject -namespace root\virtualization -class Msvm_ComputerSystem -filter " ElementName <> Name"

Another interesting property is the EnabledState property. According to the documentation here, it indicates the current state of a system. It is always set to 2 ( Enabled) for a host system but for virtual systems, it can take one of the following values:

2 - Enabled ; 3- Disabled; Paused - 32768 ; Suspended - 32769

Values in the range [32770-32775] indicate transitional states of a system: Starting, Suspending, Saving....

Now that you discover, how can you change the state of a given machine? Well, the Msvm_ComputerSystem class has a method called RequestStateChange that you can use to perform actions such as, turn off, pause or save state of a virtual system. Its first parameter is of type Integer and can take on of the values described above. Here is an example:

First find a virtual machine to work with
PS C:\> $Core = get-wmiobject -namespace root\virtualization -class Msvm_ComputerSystem -filter " ElementName = 'IIS-CORE' "

Then check is current state
PS C:\> $Core.EnabledState

Put this machine in saved state
PS C:\> $Core.RequestStateChange(32769)

Start this machine
PS C:\> $Core.RequestStateChange(2)

Isn't it easy?

Summary

In this blog entry, we discover the namespace of the Hyper-V WMI provider and use get-wmiobject to find all the classes exposed through this provider.
We then use the Msvm_ComputerSystem class to find all virtual machines as well as some interesting properties such as ElementName and EnabledState. Finally we call the RequestStateChange method of this class to power-on a VM and save its state.

Hope you enjoy it!

Until the next time....

/Dung

 HyperV WMI PowerShell