Windows Management Instrumentation:
Administering Windows and Applications Across Your Enterprise

ne of the greatest challenges facing an enterprise developer is the management of computer networks as they become larger and more complex. Windows® Management Instrumentation (WMI) is a powerful technology that makes it possible to manage a single machine, or ten thousand all at once. Unfortunately, WMI is probably one of the best-kept secrets to come out of Microsoft in recent years. It hasn�t received much coverage compared to technologies such as Active Directory™ or Windows DNA. This article will take you on a tour of WMI, so you�ll have the background you need to write your own applications using WMI. Before long you�ll be convinced that WMI should be as much a part of every developer�s vocabulary as COM, Win32®, or Microsoft.

Overview

The Genesis of WMI

CIM Classes

  
[abstract] class Automobile
{
    [key] string Make;
    [key] string Model;
    void Recall();
};
class Car : Automobile
{
    real32 BlueBookValue;
};
class Truck : Automobile
{
    uint32 Axles = 2; 
};

      The previous MOF file defines an Automobile as a base class with two subclasses: Car and Truck. An Automobile has a Make property, a Model property, and a Recall method. A Car has an additional property, BlueBookValue. A Truck has an Axles property, with a default value of 2. (New instances of Truck will have a value of 2 for Axles unless otherwise specified.) The words in brackets (abstract and key) introduce the CIM concept of qualifiers. Qualifiers can be applied to the entire class, a property, a method, or even an individual method parameter. Qualifiers are similar to the concept of attributes in IDL files. They provide additional descriptive information about the use of a class, property, or method.
      In this example, the abstract class qualifier tells you that you will never see instances of an Automobile. On the other hand, you can instantiate a Car or Truck since these are not abstract classes. The key property qualifier tells you that any Automobile (or any instance of a derived class) can be uniquely identified by its Make and Model. This is a concept borrowed from database technologies. All classes that support multiple instances must specify the key properties. Each instance must have a unique combination of values for its keys. In other words, the Automobile class definition allows for the existence of only one instance of a Ford Mustang, but you can create an instance of a Ford Taurus or even a GM Mustang. If a class has one and only one instance, it can be declared with the singleton class qualifier. In this case, the class does not have to specify any properties as keys.
      The MOF file format is used to describe instances as well as class definitions. The following example describes an instance of a Truck:

  
instance of Truck
{
    Axles = 5;
    Make = "Ford";
    Model = "Big Rig";
};

      The CIM standard alone is not enough to enable companies to create manageable objects and prevent chaos. For example, one company might call a router a NetworkRouter while another company calls the same thing a Router. Even worse, two companies could attempt to define a Router with the same class name, but different properties. To prevent this sort of confusion, the DMTF also defines the CIM schema. A schema is a well-defined collection of class definitions that all companies agree to follow. Classes that are a part of the CIM schema start with CIM_ by convention (such as CIM_Battery or CIM_Process). The CIM schema makes heavy use of inheritance to allow management applications to treat groups of similar objects in the same way. For example, CIM_Battery, CIM_Printer, and CIM_Processor are all derived from the base class CIM_LogicalDevice. This allows management applications that know how to work with a CIM_LogicalDevice to manage any type of device derived from that class. In addition, any derived class will support the properties and methods of the base class. The class CIM_LogicalDevice has a property that specifies if power management is supported (PowerManagementSupported), and a method that allows the power state to be set (SetPowerState). By exposing this functionality in the base class, applications can manage the power state for a printer, processor, or any device derived from CIM_LogicalDevice.
      Another benefit of inheritance is that vendors can extend the CIM schema if they are able to provide more information than the CIM classes define. For example, the Windows operating system may know the AveragePagesPerMinute of installed printers. The CIM_Printer class does not define a property for this information, so Microsoft defines a Win32_Printer, derived from CIM_Printer, that has the additional property AveragePagesPerMinute. A management application that knows about the Win32_Printer class can use this information, but an application that only knows how to manage a CIM_Printer will still function properly.

WBEM Support

WMI Architecture

Namespaces

Figure 4 Exploring Namespaces

      As mentioned earlier, one of the core components to the WBEM initiative is to support the classes defined in the CIM schema. In WMI, these classes can be found in the root\cimv2 namespace. The CIM schema is continually updated, but each release is described with a version number. The v2 part of the root\cimv2 namespace means that the schema represented is the CIM Version 2 schema. Microsoft has also developed custom schemas for information not represented by the CIM V2 schema. These schemas are stored in other namespaces, such as root\WDM for information provided by WDM drivers, or root\directory\LDAP for information provided by the Active Directory provider. Developers who are providing their own schemas can create new namespaces. In fact, unless you are extending a schema by deriving from an existing class, it is best to create new classes in your own namespace.

System Classes and System Properties

Object Paths

  
Win32_Environment.Name="TEMP",UserName="JEFFC\\Administrator" 

refers to the instance of Win32_Environment where the Name property is TEMP and the UserName property is JEFFC\Administrator. Note that the \ was expressed as \ when quoted in the object path (just like C++ or the Java language). In the case of singleton classes (which have no key properties, but one and only one instance), the object path consists of the class name appended with =@, such as \jeffc\root\cimv2:SingletonTest=@.
      Ideally, object paths are completely case-insensitive. This means that machine names, namespace names, class names, property names, and property values are all case-insensitive. In reality, some poorly written providers may accidentally require case sensitivity for property names or values. If this is ever encountered, it should be treated as a bug by the provider. In addition to being careful when writing providers, developers must be careful that any operations performed with object paths are done in a case-insensitive manner.

Programming WMI

  
// Show free space for C: drive
WScript.Echo(diskinstance.FreeSpace);

      Property names and values can also be accessed through the Properties_ collection:

  
// Show all properties and values using an "Enumerator"
// In VBScript, this can be done with a "FOR EACH" statement
var f=new Enumerator(diskinstance.Properties_)
for (;!f.atEnd();f.moveNext ())
{
  var prop = f.item();
  WScript.Echo(prop.Name + " = " + prop.Value);
}

Methods are accessed in a similar manner. Methods can be accessed through the Methods_ collection, and they are also appended directly onto the SWbemObject itself.
      As mentioned earlier, every object has a set of system properties that allow the identity of an object to be determined dynamically. These system properties are accessed through the Path_ property of SWbemObject. The Path_ property is an SWbemObjectPath object that has properties corresponding to each system property. The naming convention is not identical to the names of the system properties, but the mapping is fairly obvious. The following function shows how to dynamically determine if an object is a class or an instance:

  
function IsObjectAClass(obj)
{
  // Internally, IsClass uses the __Genus system property
  // to determine if an object is a class or instance
  return obj.Path_.IsClass;
}

      Until now, the examples have assumed that you know the object path of the class or instance you want to examine. The SWbemServices object also allows you to dynamically query for available classes or instances. The list of available classes can be determined through the SubclassesOf method. This method returns the subclasses of a given class or the list of base classes if no class is specified as an argument. To allow for instances to be retrieved dynamically, WMI again borrows a technique from the database world; it uses a variation of SQL called the WMI Query Language (WQL). Here�s an example of a simple WQL query that retrieves the list of all logical drives:

  
SELECT * FROM Win32_LogicalDisk

      Just as with SQL, WQL queries can be refined to return a specific set of properties, or a subset of instances that satisfy some criteria. The full syntax of WQL queries is documented in the Platform SDK, but some examples can help show the power of WQL. The following query returns the list of all services that are stopped:

  
SELECT * from Win32_Service WHERE State="Stopped"

This query returns only the Name and FreeSpace properties of all logical disks:

  
SELECT Name,FreeSpace FROM Win32_LogicalDisk

      To execute a WQL query, you can use the ExecQuery method of SWbemServices. The ExecQuery method will return a collection of objects that meet the criteria specified in the query. The following sample will output the name, free space, and total size for every logical drive:

  
// Sample2.js
var locator = new ActiveXObject("WbemScripting.SWbemLocator");
var service = locator.ConnectServer();
var props = service.ExecQuery("SELECT Name,FreeSpace
                              FROM Win32_LogicalDisk");
var f = new Enumerator (props);
for (;!f.atEnd();f.moveNext ())
{
  var p = f.item ();
  WScript.Echo(p.Name + " - " + p.FreeSpace + " - " + p.Size);
}

      If you run the previous script from a console window (using the command cscript SAMPLE2.JS), the output will look something like this:

  
A: - 18432 - undefined
C: - 1079707648 - undefined
D: - 1006243840 - undefined
E: - 553623552 - undefined
Z: - 4573265920 - undefined

Each line should show the drive name, free space, and drive size, but you�ll notice that the drive size is missing. If you look carefully at the WQL query, you�ll notice that I only asked for the Name and FreeSpace property. Since I did not request the Size property, I�m not guaranteed that it will be available in the returned objects. Limiting a WQL query to specific properties can provide a great performance boost since providers can skip properties that are costly to query, but it can leave you with SWbemObject objects that only have partial information. This can be an annoying source of bugs if you are not careful.
      The SWbemServices object provides several other methods that return collections of objects (such as InstancesOf, ReferencesTo, and AssociatorsOf). If you are working with the IWbemServices interface, you may notice that these methods are missing. This is because the extra SWbemServices methods actually generate WQL queries behind the scenes. The extra methods exist on the scripting object as a convenience that can make scripts somewhat more legible. There is no performance difference between calling InstancesOf(SomeClass) or ExecQuery(SELECT * FROM SomeClass).
      You may have noticed that the very first sample used GetObject to retrieve an SWbemServices object. Other samples have used a two-step process of creating an SWbemLocator followed by a call to ConnectServer. GetObject uses a concept familiar to COM developers called monikers. WMI supports a rich set of monikers to enable one-step access to SWbemServices and SWbemObject objects for classes or instances. The following JScript shows an example of using monikers to access the Alerter service:

  
var alerter = GetObject("WinMgmts:Win32_Service=\"ALERTER\"");

The equivalent method without monikers requires three steps:

  
var locator = new ActiveXObject("WbemScripting.SWbemLocator");
var service = locator.ConnectServer();
var alerter = service.Get("Win32_Service=\"ALERTER\"");

      The use of GetObject with monikers can be very convenient for many simple tasks. However, repeated use of monikers for objects from the same namespace may be less efficient than it would be to reuse a single SWbemServices object. A full list of all the options supported by WMI monikers is covered in the Platform SDK under the heading "Object Creation and Monikers."
      At this point, it�s worth discussing some of the tools that are out there to help browse the information that�s available through WMI. WMI ships with a test application called WBEMTest.exe. This is a very powerful app, since it provides access to almost every DCOM interface exposed by WMI, but it is very difficult for a novice to understand. The WMI SDK ships with a set of tools that make exploring WMI easy. The WMI SDK is available from https://msdn.microsoft.com/downloads/default.asp?URL=/code/topic.asp?URL=/MSDN-FILES/028/000/015/topic.xml. The complete contents of the WMI SDK are also available through the Platform SDK, but the tools are not installed by default. You�ll have to look carefully through the setup options to enable installation of the WMI Tools.

Figure 7 CIM Studio

      CIM Studio is one of the most useful tools for exploring schemas in the WMI SDK (see Figure 7). The left pane shows the inheritance tree for classes in a namespace. The right pane shows class or instance information. CIM Studio also allows you to enter WQL queries and examine the results.

Security

Figure 8 Securing WMI Access

      To provide additional protection, WMI supports traditional Windows NT security on each namespace. This is useful to specify restrictions such as who will be able to connect to WMI from remote machines. This can be configured through an extension to the Computer Management snap-in on Windows 2000 (see Figure 8). To access this, right-click the My Computer icon on the desktop, and then choose Manage. Under Services and Applications, choose WMI Control, then display its properties. On the Security tab, you�ll be able to set the permissions for each namespace just as you set permissions for folders on your hard drive. If you are running Windows 9x or Windows NT 4.0, running WBEMCNTL.EXE will bring up the same utility. When connecting to a machine running Windows 9x, there is no support for Windows NT security on the objects managed through WMI. However, WMI allows namespaces to be configured with simulated Windows NT permissions. This lets an administrator control who connects to a namespace, but once connected, the client will essentially have full control over the objects exposed.

Events

  
SELECT * FROM MyModem_Ring WHERE CallerIDName="Stephanie"

      In addition to events defined by providers, applications can register for events that monitor changes in classes or instances. This is very powerful since it allows an application to respond to any change in state that is exposed through WMI. The code in Figure 9 shows how easy it is to monitor the creation of arbitrary objects. The HTML Application (HTA) watches for the creation of any new process.
      Copy the code in Figure 9 into a file called NewProcs.HTA, and launch the file from Explorer. HTA files are very similar to HTM files, but run with lower security restrictions. Since WMI exposes low-level functionality of the operating system, the scripting objects are not marked as safe for scripting. This does not mean that you should not script these objects. But you should not allow untrusted HTM files to script WMI. If you use WMI scripting objects in HTM files, you�ll receive security warnings about using objects not marked as safe for scripting. When you launch an HTA file, the system grants it the same access as if you launched an executable. This allows WMI scripting objects to be used without generating additional warnings.
      As you launch new processes, you should see each process name show up in the sample application. This sample introduces two new concepts. First, you register for events using a WQL event query with the ExecNotificationQueryAsync method. The full syntax of WQL event queries is covered in the Platform SDK, but the code in Figure 9 can serve as a template for monitoring instance creation for any class.
      WMI providers are responsible for notifying WMI when new instances are created, but this is only an optional requirement. If a provider does not provide notification for a particular class, applications can still register for instance creation notification, and WMI will simulate the event by polling the provider for the list of instances. The WITHIN 1 clause tells WMI that it should poll every second for new instances of the Win32_Process class. Unfortunately, the polling method is not foolproof. If a process is created and destroyed within the 1 second between the queries made by WMI, applications will not receive an event notification. Even with this limitation, though, events are remarkably powerful.
      In addition to querying for instance creation, it is possible to watch for instance deletion or modification of specific properties of an instance. Figure 10 shows how an application can monitor for the insertion of a disk into a floppy drive. This is done by watching for changes to the A: logical disk. When the Size property changes, and the new Size is greater than zero, you can assume that a disk has been inserted. This is not a very graceful sample, but it shows how a creative WQL query can generate events to respond to almost any condition in the system.
      The second new concept, introduced in Figure 10, is the use of SWbemSink. Sinks are used to perform asynchronous operations with the scripting interface. The variable mysink is created through the class ID for SWbemSink. The sink can then be used in any SWbemServices method that returns information asynchronously. When asynchronous data becomes available, the sink will fire events and pass the data to the application. In the previous examples, I used the ExecNotificationQueryAsync method to register the mysink object with the WQL event query. When the specified event occurs, the mysink object fires an OnObjectReady event. The handler for the OnObjectReady event adds text to the bottom of the HTML document.
      There are three more samples I�ve included in the code download that demonstrate most of the concepts covered in this article. (The code is available from the link at the top of this article.) KillCalc.vbs is a VBScript file that terminates all running instances of CALC.EXE. ProcTree.HTA uses the ParentProcessId property of Win32_Process to generate a parent/child tree of all the running processes in the system. This sample is not optimized for performance, but it demonstrates the sort of useful information you can get from WMI that sometimes is not exposed through the Win32 API. Finally, PrcWatch.HTA demonstrates advance uses of sinks. This sample shows a list of all processes launched by EXPLORER.EXE. It presents them in a table with a Delete button that will kill each process (make sure you have x.gif in the same directory). As new processes are launched from Explorer, they are added to the table. As processes go away, they are removed from the table. This sample also shows how to use a single sink with more than one concurrent asynchronous request.

Conclusion