Take Advantage of Scriptomatic 2.0 to Maximize Your WMI Scripting Efforts

Downloads
44360.zip

Scriptomatic 2.0 will soon be released. Many of you are probably saying, "It's about time!" Scriptomatic 2.0 certainly improves on its predecessor, and I cover many of those improvements in Rem "Scriptomatic 2.0 Is Worth the Wait." The purpose of this article is to help you get the most out of Scriptomatic 2.0. Microsoft's Scripting Guys intended that this tool be used to help novice Windows Management Instrumentation (WMI) scripters see the consistency inherent in WMI scripts that read WMI class properties. The tool accomplishes this task quite well. However, it also serves as an excellent launching point to building more sophisticated scripts. In this article, I explain what you can infer from the information Scriptomatic provides, point you to important tools that expand on the information provided by Scriptomatic, and demonstrate how you can augment the Scriptomatic code so that it provides even more class information.

What's on the Surface
The simplest and most obvious use for Scriptomatic is reading and displaying a class's properties and their values. When Scriptomatic 2.0 loads, it defaults to the root\CIMV2 namespace, then loads the classes in that namespace. You select a WMI class, such as Win32_ComputerSystem, to generate a script.

After Scriptomatic 2.0 generates the code, you can immediately run the script or save it to a file so that you can use it to create more complex code. If you run the script, you can output the results as command output in the command-shell window, as a text file for viewing in Notepad or another editor, as an HTML or XML file for viewing in a browser such as Microsoft Internet Explorer (IE), or as a comma-separated value (CSV) file for viewing in Microsoft Excel or another spreadsheet program.

If you want to build more complex code from the script, you need to have some proficiency in a scripting language such as VBScript or Perl. Scriptomatic 2.0 provides you with simple scripts in VBScript, JScript, Perl, and Python. From there, you can use your language of choice to build production-level code.

Scriptomatic 2.0 alone won't give you a complete picture, which is why you need several WMI-specific tools and references in your toolkit. Here's a list of essential WMI tools and documentation that you can use to expand on the information Scriptomatic 2.0 provides:

• WBEMTest. WBEMTest is part of every OS installed with WMI. It's not the easiest tool to master, but it has the advantage of always being there.
• WMI CIM Studio. WMI CIM Studio is a powerful and intuitive Web-based interface for digging into WMI. It's part of the WMI Administrative Tools suite. Those who don't already have this suite of tools can download it from http://www.microsoft.com/downloads/details.aspx?displaylang=en&familyid=6430f853-1120-48db-8cc5-f2abdc3ed314.
• WMI software development kit (SDK) documentation. The WMI SDK documentation is available online at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/wmisdk/wmi/wmi_start_page.asp. If you don't have an always-on Internet connection, you might prefer to download the Windows Server 2003 Core SDK from http://www.microsoft.com/msdownload/platformsdk/sdkupdate. The WMI SDK documentation is part of the Core SDK.
• "WMI Scripting Primer." I often reference the three-part article "WMI Scripting Primer" because, in relatively few pages, it provides powerful insights into the WMI architecture and the WMI scripting API. If you haven't already read this primer, I urge you to do so. "WMI Scripting Primer: Part 1" is at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnclinic/html/scripting06112002.asp. You can access the other parts from the directory on the right side of this Web page.

A Path to WMI Scripting
Scriptomatic 2.0 is a great starting point for developing powerful WMI scripts. It lets you quickly evaluate a bunch of classes and their properties in a namespace. You can determine the namespaces available in an OS. You can list properties of a class, or lack thereof. A lack of properties might suggest that the class is rich in methods. With a little support from other tools or scripts, you can find properties that you can write or change, determine the data types of available properties, and learn more about class methods.

Using Contrast as an Effective Learning Tool
Scriptomatic 2.0 lets you select other WMI namespaces besides the common root\CIMV2 namespace. CIMV2 is the only namespace available in version 1.0. In version 2.0, you can gain insight on whether a namespace (i.e., provider) is available on other platforms. For example, the root\MicrosoftIISv2 provider is available on Windows 2003 computers running Microsoft IIS 6.0. In contrast, this namespace isn't available on computers running Windows XP and IIS 5.1 because the MicrosoftIISv2 provider is available only on IIS 6.0.

To see this contrast, launch Scriptomatic 2.0 on a computer running Windows 2003 and IIS 6.0 and browse the listed WMI namespaces in the WMI Namespace drop-down list box. Then, launch Scriptomatic 2.0 on a computer running XP and IIS 5.1 and again browse the listed namespaces. You'll see that the MicrosoftIISv2 provider is available in Windows 2003 but not XP. Thus, if you're building a script to modify the IIS metabase, you'll know that IIS 6.0 has a powerful WMI provider available for that purpose. (For more information about this provider, see Rem "Using WMI to Change HTTP Compression Settings.")

You can use the contrast technique for more than WMI namespaces. After you select a namespace, you can see class differences from one OS to the next. For example, if you select the root\DEFAULT namespace on an XP or Windows Me computer with the System Restore feature enabled, you'll see the System Restore class in the WMI Class drop-down list box. In contrast, because System Restore isn't an available feature in Windows 2003, you won't see this class in the root\DEFAULT namespace. Thus, if you're building a script to configure or retrieve System Restore checkpoints, you now know that this class is available on a small subset of client OSs.

Sometimes What You Aren't Told Is a Clue
If you select a class and generate a script that returns few or no properties, you might have encountered a class with useful methods. For example, if you use Scriptomatic 2.0 to create a script for the StdRegProv class in the root\DEFAULT namespace, you'll see that StdRegProv doesn't contain any properties. (Technically, StdRegProv contains global system properties, but Scriptomatic doesn't display these types of properties because they're of little value from an administrative scripting perspective.) To determine whether a class has useful methods, you can use WBEMTest. Follow these steps to see for yourself what the StdRegProv class contains:

1. In the Run dialog box, type

   WBEMTest 

   and press Enter.
2. In the Windows Management Instrumentation Tester dialog box, click Connect.
3. Verify that root\DEFAULT appears in the first text box, then click Connect again.
4. Click the Query button.
5. In the Query dialog box, enter the query

   select * from StdRegProv

   then select the Retrieve class prototype check box. Click Apply.
6. In the Query Result dialog box, double-click StdRegProv.
7. In the Object editor for StdRegProv dialog box, locate the Methods box. Here you'll see all the methods of the StdRegProv class.
8. To verify that there aren't any local StdRegProv properties, select the Hide System Properties check box. The Properties box should now be empty.
9. To see the input parameters (also called properties) for a specific method, you can double-click a method. For example, double-click the CreateKey method.
10. In the Method Editor dialog box, click the Edit Input Arguments button.
11. In the Object editor for __Parameters dialog box, make sure that the Hide System Properties check box is selected. You'll see two input parameters in the Properties box: hDefKey and sSubKeyName. If you used the CreateKey method, the hDefKey parameter's value will be an integer that represents the registry key in which you created your new subkey. The sSubKeyName parameter's value will be a string that specifies the new subkey's pathname. Note that you can use the WMI SDK to review the numeric values of registry keys.

If you've installed the WMI Administrative Tools, you can view similar information with CIM Studio. Follow these steps to view the StdRegProv methods in CIM Studio:

1. Open CIM Studio. If you've installed XP Service Pack 2 (SP2) with pop-up blocking, you have to select Allow Blocked Content so that CIM Studio (an IE application with active content) can run.
2. When the Connect to namespace dialog box appears, change the path to root\DEFAULT and click OK.
3. In the WMI CIM Studio Login dialog box, click OK to log on as the current user.
4. In the directory on the left, click StdRegProv.
5. In the results pane, click the Methods tab. All the StdRegProv class methods will appear.
6. Right-click a method, such as CreateKey, then click Edit Method Parameters to view the method's input parameters.

After you learn which methods and properties are (or aren't) available in a class, you can obtain more information about them from the Microsoft Developer Network (MSDN) Library or the WMI SDK. For example, you can read about the StdRegProv class's CreateKey method in the MSDN Library at http://msdn.microsoft.com/library/default.asp?url=/library/enus/wmisdk/wmi/createkey_method_in_class_stdregprov.asp.

As the StdRegProv example illustrates, the lack of properties often suggests that a class has a rich set of methods. However, a class with many properties might also contain a rich set of methods. For example, the Win32_Share class in root\CIMV2 contains 10 nonsystem properties and four methods. Therefore, don't assume that a class containing nonsystem properties will contain no useful methods.

What You See Isn't Necessarily All You Get
Scriptomatic 2.0 is a great tool for quickly learning the properties of a class, but it won't tell you anything about whether those properties are read-only or writeable. However, in many cases, you can deduce whether a property is read-only or writeable just by the type of class to which the property belongs. Take, for example, the Win32_BIOS class in the root\CIMV2 namespace. It's atypical for an application to write changes to the BIOS outside of the BIOS setup utility, so the Win32_BIOS class contains read-only properties, such as BIOSVersion and Manufacturer.

Other classes, such as IIsCompressionSchemesSetting of the root\MicrosoftIISv2 namespace, contain a plethora of writeable properties. You can use WBEMTest or CIM Studio to verify that properties are writeable. The following procedures on how to use these tools for this purpose are abbreviated because I explained earlier how to use WBEMTest and CIM Studio. To check for writeable properties with WBEMTest, follow these steps:

1. On a computer running Windows 2003 and IIS 6.0, connect to the root\ MicrosoftIISv2 namespace. Note that you can use WBEMTest to connect to a remote computer by appending \\computer name (where computer name is the name of the computer to which you want to connect) to the namespace path appearing in the Connect dialog box.
2. Click the Query button.
3. In the Query dialog box, enter the query

   select * from
     IIsCompression-SchemesSetting

   then select the Retrieve class prototype check box. Click Apply.
4. Double-click IIsCompressionSchemesSetting. In the Properties box that appears, double-click HcDoOnDemandCompression.
5. Notice that write is set to True in the Qualifiers box and that the CIM type is Boolean.

To check for writeable properties in CIM Studio, follow these steps:

1. On a computer running Windows 2003 and IIS 6.0, connect to the root\MicrosoftIISv2 namespace. You can connect to a remote computer from CIM Studio by specifying \\computer name in the Machine Name text box of the Browse for Namespace dialog box.
2. In the directory, expand the CIM_Setting\IIsSetting path, then click IIsCompressionSchemesSetting. In the results pane, a writeable property has a special icon. Figure 1 shows the icon for writeable inherited properties. Figure 2 shows the icon for writeable local properties. You can also see whether a property is writeable by following the next step.
3. In the results pane, double-click a property, such as HcDoOnDemandCompression. In this case, you'll see that the write value is set to True and the CIM type is Boolean.

When you know which class properties are writeable, you can use Scriptomatic 2.0 to create a script, then adapt that script to modify those properties' values. For example, let's say you want to change the HcDoOnDemandCompression property's value. Follow this procedure on a computer running Windows 2003 and IIS 6.0 on a nonproduction system, lab computer, or virtual hard disk:

1. Open Scriptomatic 2.0. Select root\MicrosoftIISv2 in the WMI Namespace box and IIsCompressionSchemesSetting in the WMI Class box to generate the script.
2. Run the script from within Scriptomatic to determine the value of the HcDoOnDemandCompression value.
3. Close the command-shell window.
4. Edit the script from within Scriptomatic. Remove all the properties except for the HcDoOnDemandCompression property. You'll see all the properties listed in the For Each...Next statement that begins with the line

   For Each objItem in colitems

5. Add the code that callout A in Listing 1 shows. The first line changes the HcDoOnDemandCompression property's value. Change the value to False if Scriptomatic displayed a True value in Step 2, or vice versa. The second line uses WMI's SWbemObject.Put_ method to write the changes to the IIS metabase. For more information about the Put_ method, see "WMI Scripting Primer: Part 2."
6. Click Run to run the script.

After about 5 minutes, the change will be written to the IIS metabase. This example is intended only to demonstrate how you use WMI with a writeable property. For information about configuring HTTP compression, see Rem "Using WMI to Change HTTP Compression Settings."

Reading Between the Lines
A crucial aspect of creating most types of scripts is understanding the data types of the properties you're reading or writing—and creating WMI scripts is no exception. Scriptomatic 2.0 can help you gain some insight on WMI data types even though it doesn't explicitly specify the data types. To determine the data types, you need to review the Scriptomatic script and the script's output. For example, Scriptomatic displays properties with Boolean data types, String data types, and Integer data types simply by calling the name of the property in the script. The script and output for the Win32_ComputerSystem class in the root\CIMV2 namespace provide a good example of how you can deduce these three data types:

• The script calls the objItem.BootupState property, which specifies a computer's boot-up state. In the output, the property's value is a phrase, such as Normal boot. Thus, you can deduce that this property has a String data type.
• The script calls the objItem.InfraredSupported property, which specifies a computer's support for infrared technology. In the output, the property's value will be either True or False. Thus, you can deduce that this property has a Boolean data type.
• The script calls the objItem.DomainRole property, which specifies the role of a computer in a domain. In the output, the property's value is a number between 0 and 5. Thus, you can deduce that this property has an Integer data type.

You can also deduce other data types by looking at the script Scriptomatic creates. For example, Scriptomatic 2.0 uses the Join function to display properties stored as arrays (Array data type) and the WMIDate-StringToDate function, which callout B in Listing 1 shows, for a property whose value is stored as a DateTime data type.

Getting a Bit More Scientific
Scriptomatic 2.0 is helpful in uncovering important details about a class and its properties, but the approach I outline in this article requires that you verify the information by using other tools, such as WBEMTest, CIM Studio, or MSDN Library documentation. Also, Scriptomatic isn't designed to uncover much about a class's methods and method parameters.

Instead of relying on other tools to help you fill the gaps, you can augment Scriptomatic's script output with the GetDataTypes function, which callout B in Listing 2 shows. This function, whose code is described in detail in "WMI Scripting Primer: Part 2," displays a class's properties and methods and their corresponding data types and parameters. In contrast to the code in "WMI Scripting Primer: Part 2," the code in Listing 2 is modified slightly to limit the display of data.

To use the GetDataTypes function in a script, follow these steps:

1. Open Scriptomatic 2.0 and select a namespace from the WMI Namespace box and a class from the WMI Class box to generate a script.
2. Verify that VBScript is the selected language, and make sure that you have only one computer listed in the Target Computers (comma-delimited) text box.
3. Add the line that callout A shows. Be sure to add this code inside the outer For Each loop and replace the namespace and class name with the corresponding values that appear in the WMI Namespace and WMI Class boxes.
4. Add the code that callout B shows. Be sure to add this code at the bottom of the script.
5. Select the XML output format, then run Scriptomatic. When IE opens, the class's properties and their data types, as well as the class's methods and their associated parameters and data types, will be appended to the display.

Make Scriptomatic 2.0 Part of Your WMI Scripting Toolkit
The Scripting Guys chuckle when people say that Scriptomatic has its weaknesses as a development tool. The goal for Scriptomatic all along has been to serve as a learning tool to help the novice WMI scripter see the consistency inherent in WMI scripts that read class properties. Scriptomatic does a great job of providing this insight. Clearly, though, this tool has gotten a lot of attention by scripters who are well beyond the novice stage. This attention is warranted because Scriptomatic is a wonderful tool for quickly uncovering class details indirectly, as I describe in the first part of the article, and directly by augmenting the Scriptomatic code, as I demonstrate in the last part of this article.