We all know that IT is an ongoing educational experience. Most of that learning is incremental. I can only point to a few times in my career in which a single educational endeavor translated directly to a major change in the course of my career. One of those was reading Richard Siddaway’s PowerShell and WMI. It’s old enough that large patches of the examples in that work are outdated, but the lessons and principles are sound. I can tell you that it’s still worth the purchase price, and more importantly that if this man says anything about WMI, you should listen. You can imagine how excited I was to see that Richard had begun contributing to the Altaro blog.

WMI can be challenging though, and it doesn’t help when you can’t find solid information about it. I’m here to fill in some of the blanks for WMI and Hyper-V 2016.

What is WMI?

WMI stands for “Windows Management Instrumentation”. WMI itself essentially has no substance; it’s a Microsoft-specific implementation of the standardized Common Information Model (CIM), maintained by the DMTF. CIM defines common structures and interfaces that anyone can use for a wide range of purposes. Most purposes involve systems monitoring and management. The simplest way to explain WMI, and therefore CIM, is that it is an open API framework with standardized interfaces intended for usage in management systems. PowerShell has built-in capabilities to allow you to directly interact with those interfaces.

What is the Importance of Hyper-V and WMI?

When it comes to Hyper-V, all the GUIs are the beginner’s field. The PowerShell cmdlets are the intermediate level. The experts distinguish themselves in the WMI layer. Usually, when someone incredulously asks me, “How did you do that?”, WMI is the answer. WMI is the only true external interface for Hyper-V. All of the other tools that you know and love (or hate) rely on WMI. However, none of those tools touch all of the interfaces that Hyper-V exposes through WMI. That’s why we need to be able to access WMI ourselves.

How Do I Get Started with Hyper-V’s WMI Provider?

If you don’t already know WMI, then I would recommend Richard’s book that I linked in the first paragraph. The “warning” that I would tell you on that is to not spend a lot of time learning about associators. You won’t use them with v2 of the Hyper-V WMI provider. Instead, you’ll use $WMIObject.GetRelated(), which is much easier. There are other ways to learn WMI, of course, but that’s the one that I know. Many of the PowerShell scripts that I’ve published on this blog include WMI at some point, so feel free to tear into those. Also try to familiarize yourself with the WMI Query Language (WQL). It’s basically a baby SQL.

Get a copy of WMI Explorer and put it on a system running Hyper-V. Use this tool to navigate through the system. In this case, you’re especially interested in the rootvirtualizationv2 branch. No other tool or reference material that you’ll find will be as useful or as accurate. You can use it to generate PowerShell (check the Script tab). You can also use it to generate MOF definitions for classes (right-click one). It’s a fantastic hands-on way to learn how to use WMI and discover your system.

undoc_wmiexplorer

Microsoft does publish documentation on the Hyper-V WMI provider. Starting with 2016, it is not thorough, it is not current, and someone had the brilliant idea to leave it undated so that you won’t be able to determine if it’s ever been updated. There are more than a few notes that make it worthwhile enough to use as a reference.

Do not forget search engines! If you just drop in the name of a class, you’ll find something, and often a useful something. It doesn’t hurt to include “v2” in your search criteria.

Undocumented and Partially Documented WMI Changes for Hyper-V 2016

Some of this stuff isn’t so much “undocumented” so much as unorganized. The goal of this section is to compile information that isn’t readily accessible elsewhere.

Security and the Hyper-V WMI Provider

It is not possible to set a permanent WMI registration on any event, class, or instance in the Hyper-V WMI provider. The reason is that permanent subscriptions operate anonymously, and this particular provider does not allow that level of access. You can create temporary subscriptions, but that’s because they must always operate under a named security context. Specifically, a user name.

I don’t have much more to give you on this. You can see the symptoms, or side effects if you will, of the different security restrictions. Many things, like Get-VM, don’t produce any results unless you have sufficient permissions. Other than that, you’ll have to muddle through on your own just as I have. My best sources on the subject say that there is no documentation on this. Not just nothing public, just nothing. That means that there is probably a lot more that we could be doing in terms of providing controlled access to Hyper-V functions.

What Classes Were Removed from the Hyper-V WMI Provider in 2016?

I pulled a list of all classes from both a 2012 R2 system and a 2016 system and cross-referenced the results. The following classes appear in 2012 R2 but not in 2016:

I have never personally used any of these classes, so I’m not going to miss them. If you have any script or code that expects these classes to exist, that code will not function against a 2016 system.

One retired class of interest is “Msvm_ResourceTypeDefinition”. As we’ll see in a bit, the way that virtual machine components are tracked has changed, which could explain the removal of this particular class.

What Classes Were Added to the Hyper-V WMI Provider in 2016?

The results of the previous test produced a great many new classes in 2016.

If you’re aware of the many new features in 2016, then the existence of most of these new classes makes sense. You can’t find documentation, though. If you want to see one of the shortest Google results lists in history, go search for “Msvm_TPM”. I got a whopping three hits when I ran it, with no relation to Hyper-V. After publication of this article, we’ll be up to a staggering four!

Some of these class additions are related to a breaking change from the v2 namespace in 2012 R2: some items that were formerly a named subtype of the Msvm_ResourceAllocationSettingData class now have their own specialized classes.

What Happened to the Serial Port Subtype of Msvm_ResourceAllocationSettingData?

First, let’s look at an instance of the Msvm_ResourceAllocationSettingData class. The following was taken from WMI Explorer on a 2012 R2 system:

undoc_serialportsubtypeI’ve highlighted two items. The first is the ID of the virtual machine that this component belongs to. The second is the “ResourceSubType” field, which you can use to identify the component type. In this case, it’s a virtual serial port.

I chose to use WMI Explorer for this example because it’s a bit easier to read. The following code block shows three ways that I could have done it in WMI by starting from the virtual machine’s human-readable name:

The first technique utilizes the skills of the .Net and PowerShell savvy. The second and third methods invokes procedures familiar to SQL gurus.

Now that we’ve seen it in 2012 R2, let’s step over to 2016. I have configured the above virtual machine in Hyper-V Replica between 2012 R2 and 2016, so everything that you see is from the exact same virtual machine.

To begin, all three of the above methods return no results on 2016. The virtual machine still has its virtual serial ports, but they no longer appear as instances of Msvm_ResourceAllocationSettingData.

Now, we have:

Msvm_SerialPortSettingData

Msvm_SerialPortSettingData

I’ve highlighted a couple of things in that second entry that I believe are of interest. This entry certainly looks a great deal like the Msvm_ResourceAllocationSettingData class from 2012 R2, doesn’t it? However, it is an instance of Msvm_SerialPortSettingData. Otherwise, it’s structurally identical. You can even search for it using any of the three methods that I outlined above, provided that you change them to use the new class name.

I did not find any other missing subtypes, but I didn’t dig very deeply, either.

Associator Troubles?

I mentioned a bit earlier that I don’t use associators with the v2 namespace. I have seen a handful of reports that associator calls that did work in 2012 R2 do not work in 2016, although I have not investigated them myself. If that’s happened to you, just stop using associators. .Net and PowerShell automatically generate a GetRelated() method for every WMI object of type System.Management.ManagementObject. It has an optional String parameter that you can use to locate specific classes, if you know their names.

Find everything directly related to a specific virtual machine:

Find a specific class related to a specific virtual machine:

What the tools that I’ve shown you so far lack is the ability to quickly discover associations. The GetRelated() method allows you to discover connections yourself. To keep the output reasonable, filter it by the __CLASS field (that’s two leading underscores). The following shows the commands and the output from system:

You can use this technique on the Script tab in WMI Explorer (which will run the script in an external window) and then cross-reference the results in the class list to rapidly discover how the various classes connect to each other.

You can also chain the GetRelated() method. Use the following to find all the various components of a virtual machine:

Put WMI to Work

WMI is the most powerful tool that a Hyper-V administrator can call upon. You don’t need to worry about hurting anything, as you would need to directly call on some method in order to make any changes. The Get-WmiObject cmdlet that I’ve shown you has no such powers.

If you’re willing to go deeper, though, you can certainly use WMI to change things. There are several properties that can only be changed through WMI, such as the BIOS GUID. In previous versions, some people would modify the XML files, but that was never supported. In 2016, the virtual machine file format is now proprietary and copes with manual alterations even more poorly than the old XML format. To truly sharpen your skillset, you need to learn WMI.