WMI: MOF Basics

• Download source code - 8.49 KB

Introduction

WBEM (Web-Based Enterprise Management) is an industry initiative for standardization of enterprise environment management. WBEM comprises a set of standards developed and maintained by DMTF (Distributed Management Task Force). WMI (Windows Management Instrumentation), the Microsoft implementation of WBEM, is widely used by system administrators and developers as a tool for managing Windows systems.

WMI uses the CIM (Common Information Model) standard to represent various Windows components. CIM is an information model that describes enterprise elements available for management. There are two important parts of CIM: CIM Specification and CIM Schema.

CIM Schema consists of a set of classes that represent entities available for management. It's Core Model contains classes at the highest abstraction level, like CIM_ManagedElement, CIM_Setting, and CIM_Location. These classes' derivations are used to compose CIM Schema Common Models, each of which describes a distinct management area (for example, Systems, User, Network, Applications etc.). Each Common Model is used as a base for platform-specific extensions, classes that represent concrete, real-world elements you can use for management.

The CIM specification defines elements that can be used to express the management model. Some of these elements are:

• Schemas. A schema is a group of classes with a single owner. Each class name includes the schema name. For example, the CIM_DataFile, Win32_Process, and MSFT_WmiCoreEvent classes belong to schemas named CIM, Win32, and MSFT.
• Classes. A class is a prototype that defines properties and methods common to a class of objects.
• Properties. Properties describe the data of the class.
• Methods. Methods describe the behavior of the class.
• Qualifiers. Qualifiers provide additional information about classes, properties, and methods. The CIM_DataFile.Name property has a qualifier named 'Key' of boolean type and its value is True.

The CIM Specification defines the syntax and rules of the model, including the CIM syntax language called MOF (Managed Object Format). In this article, I will attempt to present the basics of MOF usage, along with some simple examples.

Microsoft CIM Implementation

WMI is Microsoft's implementation of CIM. For the model to be functional, it needs to have two components: CIM Repository and CIMOM (CIM Object Manager). The Repository stores class definitions and also, in some cases, instance definitions (but this is an exception - most instance definitions are retrieved dynamically by WMI providers). For Windows systems, the Repository is located in the %Windir%\System32\wbem\repository directory (typically, c:\windows\system32\wbem\repository\).

CIMOM is an object broker between the Repository and management data consumers: it serves consumer requests for data retrieval, modification, or addition to the Repository. Microsoft's implementation of CIMOM is a Windows Service called WinMgmt.exe, also located in %Windir%\System32\wbem directory (or c:\windows\system32\wbem\).

A WMI consumer is any application that interacts with WMI. WMI providers are DLLs that dynamically provide management data from various Windows subsystems to WMI.

Working with Samples

An MOF file is a textual file that contains a series of class and instance definitions. Each definition ends with a semicolon (;). MOF files can also contain comments and pragma directives.

To add the object definitions contained in a MOF file to the WMI repository, you need a tool called mofcomp.exe (also located in the %Windir%\System32\wbem directory). Mofcomp.exe supports a number of command-line switches that control its behavior, but its basic syntax is:

mofcomp FileName.mof

If there are no errors, this command will add class and instance definitions from Filename.mof to the WMI repository.

WMI Tools

Wbemtest.exe is a WMI testing tool and is distributed with every Windows installation. You can invoke it from the Command Prompt by typing 'wbemtest', or from Start -> Run -> wbemtest. A more user-friendly tool for working with WMI is called CIM Studio, which is freely downloadable from the Microsoft website. If you don't already have CIM Studio installed, I suggest that you install it and use it when working with WMI.

When you start the CIM Studio, you are presented with a dialog box that allows you to choose a WMI namespace to connect to. After connecting, two main panes are shown: the right hand pane is a treeview that represents a hierarchical view of classes in the selected namespace. In the right hand pane, you can view class or instance details. Using the CIM Studio, you can add, modify, or delete WMI classes or instances, compile MOF files, generate MOF code from existing classes etc.

Creating a WMI Namespace

Classes in the WMI repository are organized in a hierarchy of namespaces. At the root of this hierarchy is the Root namespace, which contains several child namespaces, one of which is well known: the CimV2 namespace, the default namespace for WMI operations. Although it is possible to use the CimV2 namespace when working with samples provided with this article, it is better to create a new namespace, a namespace that you can add classes and instances to, without affecting the rest of the WMI functionality.

Here is the sample MOF code that adds a new namespace to WMI:

#pragma namespace("\\\\.\\Root")

instance of __Namespace
{
    Name = "MOFNamespace";
};

To add a new namespace, you need to perform the following:

• Change the context to the namespace that you will create a child namespace in. For this, you use the #pragma namespace directive. In this case, a child namespace will be created under Root. Instead of #pragma namespace, you can also use the -N mofcomp switch.
• Create a new instance of the __Namespace WMI system class using 'instance of' keywords.
• Set the new instance of the Name property to the name of the new namespace. In this case, it is 'MOFNamespace'.

After you compile the above MOF with mofcomp.exe, you will have a new WMI namespace: Root\MOFNamespace. If you use Wbemtest or CIM Studio to browse the newly created namespace, you will see that it is empty, except for a few WMI system classes that are automatically added to each new namespace.

Deleting a WMI namespace

After you have used a newly created namespace (MOFNamespace) for testing, you can delete it using a MOF file that contains the following text:

#pragma namespace("\\\\.\\Root")

#pragma deleteinstance
    ("__Namespace.Name='MOFNamespace'", FAIL)

To delete a WMI namespace:

• Use the #pragma namespace directive to change the mofcomp context to the parent namespace of the namespace you want to delete.
• Use the #pragma deleteinstance directive to delete the instance. #deleteinstance accepts a WMI object path as an argument, so provide it with the path of the __Namespace instance you want to delete.

Compiling the above MOF file will delete the specified namespace with all its contents, so be careful with this. You need to be strict with WMI object paths, so you can't use spaces:

"__Namespace.Name = 'MOFNamespace'"

This will produce the following error when compiled with mofcomp.exe:

An error occurred while processing item 1:
Error Number: 0x8004103a, Facility: WMI
Description: Invalid object path
Compiler returned error 0x80041001

If the namespace you try to delete doesn't exist and FAIL is used, another error is reported:

An error occurred while processing item 1:
0X80041002 Class, instance, or property '__Namespace.Name='MOFNamespace'' was not found.
Compiler returned error 0x80041001

Creating a Base Class

Most of you are probably familiar with some of the WMI classes like Win32_Process, CIM_DataFile, and Win32_Service. Here is a sample MOF file that lets you create your own WMI class:

#pragma namespace("\\\\.\\Root\\MOFNamespace")

class Test_BaseClassWithNoProperties
{
};

• Use #pragma namespace to change the mofcomp context to the namespace you want to create the new class in. Instead of #pragma namespace, you can use the mofcomp -N command line switch. If you don't specify the namespace, the new class will be created in Root\Cimv2.
• Use the 'class' keyword to let mofcomp know that you are creating a new class, followed by the class name. By convention, the class name has two parts separated by an underscore: the schema that the class belongs to and the class name itself (for example, in CIM_DataFile, CIM is the schema name and DataFile is the class name).
• Use a pair of matching braces to enclose the class body.

The above MOF code, when compiled with Mofcomp.exe, creates a new WMI class called 'Test_BaseClassWithNoProperties' under Root\MOFNamespace. Since we didn't specify any custom properties for our class, it contains only of a set of predefined WMI system properties. We didn't specify the new class parent, so it will be created as a base class: its __Superclass system property will be empty.

Adding Properties to a WMI Class

Here is a sample MOF code that creates a class and adds some properties to it:

#pragma namespace("\\\\.\\Root\\MOFNamespace")

class Test_ClassWithProperties
{
    [Key] uint32 KeyProperty;
    string StringProperty;
    boolean BoolProperty = false;
    sint32 ArrayProperty [];    
};

To add properties to a WMI class, in the class body, specify the property list in the following format for each property:

• List property qualifiers enclosed in square brackets. For example, if you start the property declaration with: '[Key]', the property will be marked as a key property of the class. Qualifiers are optional.
• State the property data type. You can find a list of available data types in the CIM Specification.
• State the property name.
• If the property has a default value, you can specify that value after the property name.
• If the property is an array, put a pair of square brackets after the property name. To specify a fixed-length array, put the array length between the square brackets.

Creating a Hierarchy

The CIM Specification follows the object oriented paradigm - you can create child classes for a given class by specifying the parent class name after the name of the child class:

class Test_DerivedClassTwo : Test_DerivedClassOne
{
    boolean BoolProperty;
    string  ArrayProperty [];       
};

To create a derived WMI class using MOF:

• Use the 'class' keyword followed by the new class name.
• Specify the parent class name, separated by a colon.
• In the class body, list the new properties of the derived class.

In the above sample, Test_DerivedClassTwo inherits all Test_DerivedClassOne properties, adding two more.

Creating an Association Class

Associations are an important part of CIM schema. To create an association class, you create a class marked with the Association qualifier, that contains references to instance classes of interest. Here is a sample MOF code:

[Association : ToInstance]
class Test_AssociationClass
{
    [Key] Test_GroupComponent ref GroupComponent;
    [Key] Test_PartComponent ref PartComponent;
};

To create an association class:

• Precede the class declaration with the 'Association' class qualifier.
• Add two properties of reference type to the class. References point to instance classes that the association class is binding (Test_GroupComponent, Test_PartComponent).

Creating Class Instances

Here is a sample MOF that creates an instance of a WMI class:

instance of Test_ClassWithProperties
{
    KeyProperty = 5;
    StringProperty = "String Value";
    ArrayProperty = {1, 2, 3, 4, 5};
    // BoolProperty is False by default
};

To create an instance of a class:

• Use 'instance of' keywords followed by the class name.
• Specify the list of properties with the appropriate values. If a property has a default value, and you don't set its value, it will be set to the default value. Array values are enclosed in braces.

Conclusion

All WMI classes presented here are static, their instances as well as their definitions are stored in the WMI repository. This is not the common case: most WMI classes are dynamic - only the class definitions are stored in the repository, while the instances are retrieved dynamically by the underlying WMI providers.

The MOF syntax is not difficult: it consists of a series of class and instance definitions that describe objects to be moved to CIMOM. But why would you want to use it? For most of the common applications, standard WMI usage, either through the System.Management .NET namespace or the WMI scripting library, is sufficient, and you don't need to be aware of MOF at all. On the other hand, creating dynamic WMI classes with MOF is useless without creating the underlying WMI provider (which is difficult). Nevertheless, there are a few scenarios in which you can use the techniques described above to solve some real world problems, and I hope to show some of them in a couple of articles that will follow.

Final Note

This article is a very brief and incomplete introduction to MOF - a more complete documentation can be found on the DMTF official site (I especially recommend the DMTF tutorial) and in MSDN. For comparison purposes, along with sample MOF files, I also include C# and VBScript samples - for me, at least, it is far easier to use MOF than the corresponding C# or VBScript code.

In the end, here are some useful links:

• DMTF Official Site
• CIM Standards
• WBEM
• DMTF Tutorial
• MSDN WMI Documentation
• MSDN MOF Documentation
• MSDN mofcomp.exe Documentation
• WMI Administrative Tools Download