Undocumented Changes to Hyper-V 2016 WMI

 

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.

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.

• Version 1 (rootvirtualization namespace): https://msdn.microsoft.com/en-us/library/cc136992(v=vs.85).aspx. This documentation is only good up through 2012, but it is in good shape.
• Version 2 (rootvirtualizationv2 namespace): https://msdn.microsoft.com/en-us/library/hh850319(v=vs.85).aspx. This documentation has issues. 2016 made changes to the namespace as it was in 2012 R2. I’m giving them the benefit of the doubt that they’re in the process of updating it, but they do not appear to be making any attempt to fork the documentation so that we can distinguish 2012/R2 from 2016. That’s why I wrote this article.

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:

Msvm_ResourcePoolComponent
Msvm_ResourcePoolRegistration
Msvm_ResourceTypeDefinition
Msvm_VirtualizationComponent
Msvm_VirtualizationComponentRegistration
Msvm_VirtualSystemResourceComponent
Msvm_VirtualSystemResourceRegistration

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.

Msvm_AssignableDeviceDismountSettingData
Msvm_AssignableDeviceService
Msvm_CollectedCollections
CIM_CollectedMSEs
Msvm_CollectedReferencePoints
Msvm_CollectedSnapshots
Msvm_CollectedVirtualSystems
CIM_Collection
Msvm_CollectionManagementService
CIM_CollectionOfMSEs
Msvm_CollectionReferencePointExportJob
Msvm_CollectionReferencePointExportSettingData
Msvm_CollectionReferencePointService
Msvm_CollectionReferencePointSettingData
Msvm_CollectionSettingData
Msvm_CollectionSnapshotExportSettingData
Msvm_CollectionSnapshotService
Msvm_ComputerSystemSummaryInformation
CIM_ElementView
Msvm_EthernetSwitchHardwareOffloadSettingData
Msvm_EthernetSwitchPortMigrationQosSettingData
Msvm_EthernetSwitchPortRdmaSettingData
Msvm_EthernetSwitchPortTeamMappingSettingData
Msvm_EthernetSwitchPortVfpSettingData
Msvm_GpuPartition
Msvm_GpuPartitionSettingData
Msvm_GuestClusterInformation
Msvm_GuestCommunicationService
Msvm_GuestCommunicationServiceSettingData
Msvm_GuestServiceInterfaceSettingDataComponent
Msvm_ManagementCollection
CIM_MemberOfCollection
Msvm_MoveUnmanagedVhd
Msvm_NetworkConnectionDiagnosticInformation
Msvm_NetworkConnectionDiagnosticSettingData
Msvm_NetworkEndpointSettingData
Msvm_PartitionableGpu
Msvm_PciExpress
Msvm_PciExpressSettingData
Msvm_ReferencePointCollection
Msvm_ReferencePointOfVirtualSystem
Msvm_ReferencePointOfVirtualSystemCollection
Msvm_ResourceDependentOnResource
Msvm_SecurityElement
Msvm_SecurityService
Msvm_SecuritySettingData
Msvm_SerialPortSettingData
Msvm_ServiceOfVssComponent
Msvm_SnapshotCollection
Msvm_SnapshotOfVirtualSystemCollection
Msvm_SummaryInformationBase
Msvm_SyntheticDisplayControllerSettingData
Msvm_SyntheticKeyboard
Msvm_SystemComponentSettingData
Msvm_TPM
CIM_TPM
Msvm_VHDSetInformation
Msvm_VHDSnapshotInformation
CIM_View
Msvm_VirtualEthernetSwitchNicTeamingMember
Msvm_VirtualEthernetSwitchNicTeamingSettingData
Msvm_VirtualMachineToDisks
Msvm_VirtualSystemCollection
Msvm_VirtualSystemReferencePoint
Msvm_VirtualSystemReferencePointExportJob
Msvm_VirtualSystemReferencePointExportSettingData
Msvm_VirtualSystemReferencePointService
Msvm_VirtualSystemReferencePointSettingData
Msvm_VirtualSystemSnapshotSettingData
Msvm_VssService

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:

I’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:

### Get a virtual machine's serial ports via WMI on 2012 R2 ###

# Start by retrieving the VM
$VM = Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ComputerSystem -Filter 'ElementName="svlmc"'

# Method 1: GetRelated #
$VM.GetRelated('Msvm_VirtualSystemSettingData').GetRelated('Msvm_ResourceAllocationSettingData') | where ResourceSubType -eq 'Microsoft:Hyper-V:Serial Port'

# Method 2: Pattern Match Virtual Machine ID #
Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ResourceAllocationSettingData -Filter ('InstanceID like "%{0}%" and ResourceSubType="Microsoft:Hyper-V:Serial Port"' -f $VM.Name)

# Method 3: Same as method 2 but with manually-specified WQL #
Get-WmiObject -Namespace rootvirtualizationv2 -query ('select * from Msvm_ResourceAllocationSettingData where InstanceID like "%{0}%" and ResourceSubType="Microsoft:Hyper-V:Serial Port"' -f $VM.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:

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:

$VM = Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ComputerSystem -Filter 'ElementName="svlmc"'
$VM.GetRelated()

Find a specific class related to a specific virtual machine:

$VM = Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ComputerSystem -Filter 'ElementName="svlmc"'
$VM.GetRelated('Msvm_SummaryInformation')

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:

$VM = Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ComputerSystem -Filter 'ElementName="svlmc"'
$VM.GetRelated() | select __CLASS

__CLASS
-------
Msvm_ReplicationRelationship
Msvm_VirtualSystemExportSettingData
Msvm_SummaryInformation
Msvm_VirtualSystemSettingData
Msvm_ReplicationSettingData
Msvm_ReplicationAuthorizationSettingData
Msvm_DiskMergeSettingData
Msvm_BaseMetricValue
Msvm_AggregationMetricValue
Msvm_AggregationMetricValue
Msvm_BaseMetricValue
Msvm_AggregationMetricValue
Msvm_VirtualSystemManagementService
Msvm_VirtualSystemMigrationService
Msvm_SecurityService
Msvm_ReplicationService
Msvm_VirtualSystemReferencePointService
Msvm_VirtualSystemSnapshotService
Msvm_VirtualSystemCapabilities
Msvm_ComputerSystem
Msvm_AggregationMetricDefinition
Msvm_AggregationMetricDefinition
Msvm_BaseMetricDefinition
Msvm_AggregationMetricDefinition
Msvm_BaseMetricDefinition
Msvm_BaseMetricDefinition
Msvm_AggregationMetricDefinition
Msvm_AggregationMetricDefinition
Msvm_BaseMetricDefinition
Msvm_BaseMetricDefinition
Msvm_AggregationMetricDefinition
Msvm_AggregationMetricDefinition

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:

$VM = Get-WmiObject -Namespace rootvirtualizationv2 -Class Msvm_ComputerSystem -Filter 'ElementName="svlmc"'
$VM.GetRelated('Msvm_VirtualSystemSettingData').GetRelated() | select __CLASS

__CLASS
-------
Msvm_ResourceAllocationSettingData
Msvm_ResourceAllocationSettingData
Msvm_SerialPortSettingData
Msvm_SerialPortSettingData
Msvm_ResourceAllocationSettingData
Msvm_ResourceAllocationSettingData
Msvm_SyntheticDisplayControllerSettingData
Msvm_GuestServiceInterfaceComponentSettingData
Msvm_HeartbeatComponentSettingData
Msvm_KvpExchangeComponentSettingData
Msvm_ShutdownComponentSettingData
Msvm_TimeSyncComponentSettingData
Msvm_VssComponentSettingData
Msvm_RdvComponentSettingData
Msvm_EthernetPortAllocationSettingData
Msvm_SyntheticEthernetPortSettingData
Msvm_ResourceAllocationSettingData
Msvm_ResourceAllocationSettingData
Msvm_ResourceAllocationSettingData
Msvm_StorageAllocationSettingData
Msvm_MemorySettingData
Msvm_ProcessorSettingData
Msvm_ComputerSystem
Msvm_VirtualSystemSettingData
Msvm_VirtualSystemSettingData
Msvm_BootSourceSettingData
Msvm_BootSourceSettingData
Msvm_BootSourceSettingData
Msvm_BootSourceSettingData
Msvm_SecuritySettingData

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.