Share via

Lesson 1: Simple WMI Tasks

  • Article

How to Run a Command-line Administration Script

important Important You must be a member of the Administrators group on the local computer to run scripts and executables, or you must have been delegated the appropriate authority. As a security best practice, log on to your computer using an account that is not in the Administrators group, and then use the Runas command to run your script or executable as an administrator. From the command prompt, type runas /user:administrative_accountname "script or executable command".

To write your command-line administration script

  1. From the Start menu, click Run.
  2. In the Open box, type Notepad, and click OK.
    Notepad opens with a new file.
  3. Create a test line by typing WScript.Echo "This is a test" for VBScript, or WScript.Echo("This is a test"); for JScript.
    Always remember that JScript is case-sensitive. Do not mix VBScript and JScript in the same file.
  4. From the File menu, click Save.
    The Save As dialog box opens.
  5. From the Save as type list box, select All Files.
    Do not save the file as Text Documents (*.txt) because it automatically adds .txt to your file name, preventing it from running.
  6. In the File name box, type the name of the file, beginning with the drive letter and full path. If your administration script is written in VBScript, save the file with a .vbs file name extension for example, C:\WmiTutorial.vbs. If your administration script is written in JScript save the file with a .js file name extension for example, C:\WmiTutorial.js.
  7. Click Save. Every time you make a change, save the file. A quick way to do this is to press the CTRL key and type S.

To set security on your command-line adminstration script

  1. From the Start menu, click Run.
  2. In the Open box, type Explorer, and click OK.
    Windows Explorer opens to display the My Documents folder.
  3. Navigate to the folder that contains your script file.
    To see your local drives, double-click My Computer.
  4. Right-click the name of your script file, and click Properties.
    The property sheet for your file opens.
  5. Click the Security tab to display the Access Control List (ACL) for the file.
    Set the ACLs to restrict access to the Administrators group. See "Access Control" in Windows Help for more information.
  6. When you are done, click OK.

To run your command-line administration script from a command-prompt window

  1. From the Start menu, click Run.
  2. In the Open text box, type Cmd, and click OK.
    A command-prompt window opens opens.
  3. Change the directory to the location of the script file.
    If the prompt says D:\> or D:\Documents and Settings\myname, and your script file is on the C drive, type C: and press ENTER. If your script file is in a subfolder on that drive, change to that folder by typing cd foldername and press ENTER.
    To view the contents of the folder you are in, type dir, press ENTER, and look for your script. After your prompt indicates that you are in the folder that contains your script, you are ready to run it.
  4. Script files run with the CScript engine.
    To run the WmiTutorial.vbs file with the CScript engine, type CScript WmiTutorial.vbs.
    A pop-up window that says This is a test might appear. When you write a longer script with multiple WScript.Echo lines, receiving a pop-up window for each one is tedious.
    To force the WScript.Echo lines to display in the command-prompt window, call your script with CScript /nologo WmiTutorial.vbs.
    Now, when you press ENTER, you should see This is a test in the command-prompt window.
  5. Now, you can switch back and forth between Notepad, where you make changes to your script, and the command-prompt window where you run your script. One time-saving feature of the command-prompt window is that you can press the up-arrow on your keyboard to automatically repeat the last line you typed.

Basic Pattern of Simple WMI Tasks

All simple WMI tasks flow in the following basic pattern:

  1. Establish a connection to WMI.
    This is optional if you are making changes to only one machine.
  2. Connect to a machine through WMI.
    This step is always necessary.
  3. Create an instance of the appropriate object from which you need to access specific data.
  4. Using the instantiated objects, make your configuration changes, which might include gathering data, changing properties, adding objects, or removing objects.
  5. 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:

vbscript 
  set  locatorObj = CreateObject("WbemScripting.SWbemLocator")
jscript 
  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 documentation 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.

vbscript 
  set  providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2", "MyMachine\administrator", "Password")
jscript 
  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 documentation 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 the IIS documentation, 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.

vbscript 
  set  nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'")
jscript 
  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.

vbscript 
set locatorObj = CreateObject("WbemScripting.SWbemLocator")
set providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2")
set nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'")
 
set providerObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2")
set nodeObj = providerObj.get("IIsWebVirtualDir='W3SVC/1/ROOT'")

set nodeObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2:IIsWebVirtualDirSetting='W3SVC/1/ROOT'")
jscript 
var locatorObj = new ActiveXObject("WbemScripting.SWbemLocator");
var providerObj = locatorObj.ConnectServer("MyMachine", "root/MicrosoftIISv2");
var nodeObj = providerObj.Get("IIsWebVirtualDir='W3SVC/1/Root'");
 
var providerObj = GetObject("winmgmts://MyMachine/root/MicrosoftIISv2");
var nodeObj = providerObj.get("IIsWebVirtualDir='W3SVC/1/ROOT'");

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:

vbscript 
  
    nodeObj.AppUnload False
jscript 
  
    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:

vbscript 
  WScript.Echo "AppRoot = " & nodeObj.AppRoot
' Or,
WScript.Echo "AppRoot = " & nodeObj.Properties_("AppRoot").Value
jscript 
  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 Important 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:

vbscript 
  
    nodeObj.AppIsolated = 1
' Or,
nodeObj.Properties_("AppIsolated").Value = 1
' Save the changes.
nodeObj.Put_
jscript 
  
    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. As we learned in Lesson 3: Organizing Data from the IIS Metabase, 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:

vbscript 
  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
jscript 
  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 IIS documentation. The next lessons are less detailed for faster reading. Remember that you can always use the documentation and CIM Studio to discover what methods and properties are available to you.