Chapter 18. WMI: Windows Management Instrumentation

It might have escaped your attention, but the Windows Management Instrumentation (WMI) service introduced with Windows 2000 has been part of every Windows version since then. The WMI service is important because it can retrieve information about nearly every aspect of your system and can even make some modifications. However, it would be beyond the scope of this book to go into WMI in greater depth because that alone could fill another volume. For this reason, we will focus on how the WMI service basically works and how PowerShell handles it.

Topics Covered:

• WMI Classes and Instances
  • Instances of a Class
  • Displaying All Properties
  • Filtering Out PowerShell Properties
  • Selecting Particular Instances
  • Directly Accessing Instances
  • Modifying Properties
  • Viewing Class Descriptions
• Invoking WMI Methods
  • Instance-based Methods
  • Listing Methods
  • Static Methods
  • Help with Classes and Methods
  • Figure 18.1: WMI classes and their methods are documented in detail on the Internet
• WMI Events
• Remote Access and Namespaces
  • Accessing WMI Objects on another Computer
  • Namespaces: WMI Extensions
• WMI and the Extended Type System
  • Converting the WMI Date Format
  • Adding On a Type Converter

WMI Classes and Instances

WMI represents the insides of your computer in the form of classes. WMI provides classes for nearly everything: processor, BIOS, memory, user accounts, services, etc. The name of a class usually consists of the "Win32" prefix and the English-language name of what that class is meant to describe. For example, the Win32_Service describes services.

Instances of a Class

If you already know the name of a WMI class, Get-WmiObject will retrieve all instances of the class for you:

If you can't remember the name of a WMI class, use the -list parameter:

Displaying All Properties

Often, only the most important properties of instances are displayed. You may remember the reason why from Chapter 5 and only if you want to display all properties. Specify one of the formatting cmdlets with an asterisk:

Filtering Out PowerShell Properties

PowerShell binds to every WMI object a number of properties that begin with a double underline character but aren't actually part of the object. PowerShell uses these additional properties to manage WMI objects, something that will become very important a little later on in connection with the PowerShell Extended Type System. You can filter out any additional properties that distract you:

Now only those properties will be displayed that begin with a letter.

Selecting Particular Instances

It's seldom that you'll find a real use for all instances of a class. That's why you should use filters. The simplest (and slowest) filter is PowerShell itself. By using Where-Object, you can make sure that only those instances that have certain properties will be listed, such as all processes that have a specific name:

It would be more efficient to pass this filter directly to WMI so that WMI will return only the instances you wanted right from the outset. To do so, use the -filter parameter. The filter that you specify with this parameter is not in PowerShell code but in the WMI query language (WQL), which in turn borrows a great deal from the SQL database query language.

In addition, you can use the -query parameter if you would like to choose which properties of the instance should be returned by WMI. The next line returns the Caption and Commandline properties for all processes beginning with the letter "p":

The result is hard to understand because PowerShell supplements every WMI object with additional internal properties. For this reason, pass it to Format-Table and specify the properties that you want to make visible:

Directly Accessing Instances

Every WMI instance has its own unique path. This path is important if you want to access a particular instance directly. The path of a WMI object is located in the __PATH property. First get a display of this property if you want to find out how the path of a specific object is structured:

The path consists basically of the class name as well as one or more key properties. For services, the key property is Name and is the English-language name of the service. If you want to work directly with a particular service through WMI, specify its path and do a type conversion. Use either the [wmi] type accelerator or the underlying [System.Management.ManagementObject] .NET type:

In fact, you don't necessarily need to specify the name of the key property as long as you at least specify its value. This way, you'll find all the properties of a specific WMI instance right away.

Modifying Properties

Most of the properties that you find in WMI objects are read-only. There are few, though, that can be modified. For example, if you want to change the description of a drive, add new text to the VolumeName property of the drive:

Three conditions must be met before you can modify a property:

• The property must allow modifications in general. Most properties are read-only.
• You require the proper permissions for modifications. The drive description applies to all users of a computer so only administrators may modify them.
• You must use Put()to save the modification. Without Put(), the modification will not take effect.

Viewing Class Descriptions

Nearly every WMI class has a built-in description that explains its purpose. You can view this description only if you first set a hidden option called UseAmendedQualifiers to $true. Once that's done, the WMI class will readily supply information about its function:

In a similarly thorough way, all the properties of the class are documented. Look it up if you want to know the intended aim of the VolumeDirty property:

Invoking WMI Methods

Basically, the same thing applies to WMI as it does to the .NET framework, and in Chapter 6 you learned that both classes and instances can provide methods, such as executable commands.

Instance-Based Methods

The instances of the Win32_Process class offer you, among other things, the Terminate() method with which you can force a process to stop running. To use Terminate(), you just need Win32_Process instances. Get-WmiObject can retrieve these for you. The next line ends all running Notepad instances. However, any unsaved work will be lost:

For every instance that Terminate() closes, it retrieves an object that is displayed in the console and that reports in ReturnValue whether the operation was carried out properly. If you want to verify its success, capture the object and inspect the ReturnValue property:

Listing Methods

Get-Member will tell you which methods a WMI object supports:

Static Methods

A WMI class directly supplies static methods, very much like static methods of a .NET class. If you want to renew the IP addresses of all network cards, use the Win32_NetworkAdapterConfiguration class and its static method RenewDHCPLeaseAll():

You get the WMI class by using type conversion. You can either use the [wmiclass] type accelerator or the underlying [System.Management.ManagementClass] .NET type. Get-Member will again retrieve the methods of the class:

Help with Classes and Methods

The methods of a WMI class are also documented in detail inside WMI. For example, you get the description of the Win32Shutdown() method of the Win32_OperatingSystem class like this:

Moreover, nearly all WMI classes have excellent documentation on the Internet. That's a good thing, too, because it's not easy to find out what the method wants from you, especially when WMI methods require arguments.

If you'd like to learn more about a WMI class or a method, navigate to an Internet search page like Google and specify as keyword the WMI class name, as well as the method. It's best to limit your search to the Microsoft MSDN pages: Win32_NetworkAdapterConfiguration RenewDHCPLeaseAll site:msdn2.microsoft.com.

Figure 18.1: WMI classes and their methods are documented in detail on the Internet

WMI Events

WMI returns not only information but can also wait for certain events. If the events occur, an action will be started. In the process, WMI can alert you when one of the following things involving a WMI instance happens:

• __InstanceCreationEvent: A new instance was added such as a new process was started or a new file created.
• __InstanceModificationEvent: The properties of an instance changed. For example, the FreeSpace property of a drive was modified.
• __InstanceDeletionEvent: An instance was deleted, such as a program was shut down or a file deleted.
• __InstanceOperationEvent: This is triggered in all three cases.

You can use these to set up an alarm signal. For example, if you want to be informed as soon as Notepad is started, type:

WITHIN specifies the time interval of the inspection and "WITHIN 1" means that you want to be informed no later than one second after the event occurs. The shorter you set the interval, the more effort involved, which means that WMI will require commensurately more computing power to perform your task. As long as the interval is kept at not less than one second, the computation effort will be scarcely perceptible. Here is an example:

Remote Access and Namespaces

Maybe you have the impression that WMI intersects with some cmdlets. That is in fact correct. Whether you use Get-WmiObject Win32_Process or better Get-Process to inspect running processes is often just a matter of taste. Even Get-WmiObject Win32_Service and Get-Service can return similar results—at least, at first glance.

WMI objects come from an entirely different source than the results of cmdlets, which is why they contain different, often additional information. Moreover, there are innumerable WMI classes for which cmdlets do not exist, because WMI is extensible and many third-party vendors create WMI extensions in additional namespaces. Finally, WMI works locally as well as remotely while most PowerShell cmdlets work only locally.

Accessing WMI Objects on another Computer

Using WMI makes remote access very easy and convenient provided that you have a network connection to the target system, sufficient permissions on that system, and no firewall is operating between you and the target system. Use the -ComputerName parameter of Get-WmiObject to access another computer system using WMI. Then specify the name of the computer after it:

If you want to log on to the target system using another user account, use the -Credential parameter to specify additional log on data as in this example:

Namespaces: WMI Extensions

WMI has a hierarchical structure much like a file system does. Up to now, all the classes that you have used have come from the WMI "directory" root\cimv2. Third-party vendors can create additional WMI directories, known as Namespaces, and put in them their own classes, which you can use to control software, like Microsoft Office or hardware like switches and other equipment.

Because the topmost directory in WMI is always named root, from its location you can inspect existing namespaces. Get a display first of the namespaces on this level:

As you can see, the cimv2 directory is only one of them. What other directories are shown here depends on the software and hardware that you use. For example, if you use Microsoft Office, you may find a directory called MSAPPS12. Take a look at the classes in it:

WMI and the Extended Type System

In Chapters 5 and 6, you learned a few things about the PowerShell Extended Type System. With its help, you can give objects new properties and methods. That is very useful in the case of WMI. The Extended Type System can do more: it can be used to add on type converters. You'll see later why that's useful.

Converting the WMI Date Format

WMI includes some untypical date formats. Particularly, the date and time format looks very weird. For example, look at the example of the Win32_OperatingSystem class:

The date and time are given as a sequence of numbers, first the year, then the month, and finally the day. Following this is the time in hours, minutes, and milliseconds, and then the time zone. This is the so-called DMTF, which is hard to read. However, you can use ToDateTime() of the ManagementDateTimeConverter.NET class to decipher this cryptic format:

You only need to take one look to see what the date and the time are now. Moreover, you can also continue to work with the time indicator in various ways, such as using New-TimeSpan to calculate current system uptime:

Adding On a Type Converter

It would be much more logical if you could convert the WMI date format by type conversion into a DateTime format, such as like this:

This fails because the standard type converter is not the right tool for this conversion. But the Extended Type System can add on not only properties and methods, but also type converters. To see how, make a type converter first:

Notepad offers to create a new file. Agree, and then type this code:

Save the code as the code has to be compiled in a DLL library. PowerShell can take care of this chore for you:

The result is the file typeconverter.dll. Now all you have to do is load it in PowerShell:

The Extended Type System must be informed that a new type converter is available. To do so, create a ps1xml file that basically contains XML data:

Agree to creation of the file, and type this code:

Save the file and import the extension into the Extended Type System:

Finally, try out the extension. From now on, PowerShell can use type conversion to convert WMI dates into DateTime specifications: