Connecting to the IIS WMI Provider

Article
06/16/2017

Use the Windows WMI classes to connect to an IIS server, after which the IIS WMI provider is used to access metabase properties and the methods that act on them.

IIS 5.1 and earlier: The IIS WMI provider is not available.

All simple WMI tasks flow in the following basic pattern

Establish a connection to WMI. This is optional if you are making changes to only one machine.
Connect to a machine through WMI. This step is always necessary.
Create an instance of the appropriate object from which you need to access specific data.
Using the instantiated objects, make your configuration changes, which might include gathering data, changing properties, adding objects, or removing objects.
If you made changes to a data store (the IIS metabase properties in this case), save them.

To establish a connection to WMI, use the following line of code in your script file. LocatorObj is a variable name that you can change to anything:

Set locatorObj = CreateObject("WbemScripting.SWbemLocator")

var locatorObj = new ActiveXObject("WbemScripting.SWbemLocator");

The WbemScripting object is the base object for WMI, in the same way that the WScript object is the basic object for general scripting tasks.

Writing scripts is a lot faster if you know your way around the necessary SDKs. Look for the SWbemLocator object in the WMI SDK, in the WMI Reference, Scripting API for WMI. Two methods are defined, one of which we use next, ConnectServer.

Look at the parameters in the help topic for the ConnectServer method. Most of the parameters are optional, and their descriptions tell you what their default values are. For example, if you do not specify a machine name when calling the method, WMI assumes you want to connect to the machine on which you run your script.

To connect to a machine with a user name and password, use the following line of code in your script file. This line might display as two separate lines on this page, but make it one line in your script file. Remember to use the same language as in the first line in your script. The user name must be an administrator on the machine. The following sample uses the administrator account itself. Replace MyMachine with the name of a machine running IIS 6.0, and replace Password with the administrator password.

set providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2", "MyMachine\administrator", "Password")

var providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2", "MyMachine\\administrator", "Password");

In JScript, \ characters are special escape characters, therefore you must type them twice. Run your script now to see if there are any errors using the ConnectServer method. If you get an error, look in the WMI SDK, in the WMI Reference, Scripting API for WMI for ConnectServer where a table of error values and possible causes might guide you to a solution. Often, the error text in the command-prompt window provides enough information.

According to this help topic for ConnectServer, the return value, providerObj, is an SWbemService object. Click the link to SWbemService on the page to view the available methods. Take a moment to get familiar with the tasks that can be performed with this WMI object. Read the descriptions of the parameters for the Get method, which we use next.

To create an instance of the appropriate IIS WMI object that is listed in the IIS WMI Provider Reference of IIS Help or the IIS SDK, use the Get method. In the following line of code, we create an instance of the IIsWebVirtualDir (WMI) object, connected to the root virtual directory of the first Web site listed on your computer.

set nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'")

var nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'");

The metabase path, W3SVC/1/Root, must match the IIS Admin object type, IIsWebVirtualDir, as listed in the Access Locations table in the Reference section for KeyType. For a different example, if you were to connect to a Web site, your IIS Admin object type would be IIsWebServer, and your key type would be W3SVC/ n, where n would be the Web site number.

We should note that there is more than one way to get to this point. If you do not need to pass a user name and password, the following table shows three ways to instantiate nodeObj. Study each option for the differences to help you better understand what the possibilities are. The first option is what you already have in your script.

' Method 1
set locatorObj = CreateObject("WbemScripting.SWbemLocator") 
set providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2") 
set nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'") 

' Method 2
set providerObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2") 
set nodeObj = providerObj.get("IIsWebVirtualDir='W3SVC/1/ROOT'") 

' Method 3
set nodeObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2:IIsWebVirtualDir='W3SVC/1/ROOT'")

// Method 1
var locatorObj = new ActiveXObject("WbemScripting.SWbemLocator"); 
var providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2"); 
var nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'"); 

// Method 2
var providerObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2"); 
var nodeObj = providerObj.get("IIsWebVirtualDir='W3SVC/1/ROOT'"); 

// Method 3
var nodeObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2:IIsWebVirtualDir='W3SVC/1/ROOT'")

Now that you have a connection to the root virtual directory of the Default Web Site, you can use the nodeObj variable to make configuration changes. See IIsWebVirtualDir (WMI) to see what methods and properties are available to you. For example, to unload the ASP application without unloading all the child applications, use the AppUnload method in following line of code:

nodeObj.AppUnload False

nodeObj.AppUnload(false);

In IIS Manager, this is the same as clicking on the Unload button of the Home Directory property page for the Default Web Site.

To view the contents of one of the properties, use one of the following lines of code:

WScript.Echo "AppRoot = " & nodeObj.AppRoot 
' Or, 
WScript.Echo "AppRoot = " & nodeObj.Properties_("AppRoot").Value

WScript.Echo("AppRoot = " + nodeObj.AppRoot); 
// Or, 
WScript.Echo("AppRoot = " + nodeObj.Properties_("AppRoot").Value)

The output of either line should be the following text:

AppRoot = /LM/W3SVC/1/ROOT

Both lines do the same thing. The second line allows for you to pass the property name as a variable, which is important if you want to write a script that allows the user to pass in a parameter as the property name. In the WMI SDK, look under SWbemObject for the Properties_ property for more information. The Properties_ property returns a set of SWbemProperty objects, which is where the Value property comes from.

Important Note:
Everything in WMI is connected by object relationships. After you access one object, you can get to other objects by calling methods that return those objects. This is why you start at the top with the WbemScripting object if you are writing scripts. In the case of the IIS WMI provider, there isn't a long chain of objects, so you can usually connect directly to the one you want.

To change one of the properties and save the changes to the IIS metabase, use the following lines of code. The Put_ method is listed in the WMI SDK under SWbemObject:

nodeObj.AppIsolated = 1 
' Or, 
nodeObj.Properties_("AppIsolated").Value = 1 
' Save the changes. 
nodeObj.Put_

nodeObj.AppIsolated = 1; 
// Or, 
nodeObj.Properties_("AppIsolated").Value = 1; 
// Save the changes. 
nodeObj.Put_();

Run your script. Is there an error? You should get the error Attempt to modify read-only object or property failed. The CIM_ManagedSystemElement class contains only the read-only properties and methods for an object. We need to connect to the IIsWebVirtualDirSetting (WMI) object to access properties that we can read and write. Delete the previous set of lines from your script, instantiate a new object, and set the AppFriendlyName property using the following code:

set nodeObj = providerObj.Get("IIsWebVirtualDirSetting='W3SVC/1/Root'") 
WScript.Echo "Before: AppFriendlyName = " & nodeObj.AppFriendlyName 
nodeObj.Description = "Default Root Application" 
' Or, 
nodeObj.Properties_("AppFriendlyName").Value = "Default Root Application" 
' Save the changes. 
nodeObj.Put_ 
WScript.Echo "After: AppFriendlyName = " & nodeObj.AppFriendlyName

var nodeObj = providerObj.Get("IIsWebVirtualDirSetting='W3SVC/1/Root'"); 
WScript.Echo("Before: AppFriendlyName = " + nodeObj.AppFriendlyName); 
nodeObj.Description = "Default Root Application"; 
// Or, 
nodeObj.Properties_("AppFriendlyName").Value = "Default Root Application"; 
// Save the changes. 
nodeObj.Put_(); 
WScript.Echo("After: AppFriendlyName = " + nodeObj.AppFriendlyName);

When you run this application, the output should be

Before: AppFriendlyName = Default Application 
After: AppFriendlyName = Default Root Application

In IIS Manager, this is the same as changing the Application name in the Home Directory property page for the Default Web Site. In this lesson, we walked through a command-line administration script in detail, showing you how to leverage the WMI SDK with the related IIS help topics.

Connecting to the IIS WMI Provider

All simple WMI tasks flow in the following basic pattern

Additional resources