Getting to Edit the Metabase

The IIS metabase

In the last issue, I introduced you to the IIS metabase and talked about its structure. This month, I go a little further and show you how to modify the values the metabase stores. This article is oriented toward the scripts and capabilities of IIS 5.0, but I'll indicate where specific differences exist.

Microsoft MetaEdit provides a GUI that's great for viewing entries in the metabase, but MetaEdit isn't always the best way to edit these entries. Windows provides several scripts that you can use to manipulate the entries in the metabase from the command line. Let's look at the most generic of these scripts—the IIS Administration Script Utility (adsutil.vbs)—in detail, then examine some more-specific scripts.

The advantage of scripts such as adsutil.vbs is that they let you use one command to retrieve and set values in the metabase. Under the covers, this and other administrative scripts make the necessary calls, to Microsoft Active Directory Service Interfaces (ADSI) and others, to carry out your desired command. Your goal as an administrator is to manage your servers and minimize the time you spend creating scripts. However, understanding how to create custom solutions that take advantage of ADSI can provide a long-term reusable component to ease your administrative duties.

The IIS Administration Script Utility
Adsutil.vbs is the most generic script in the administration scripts library and provides a command-line interface to the metabase. You can find this and the other administrative scripts in your C:inetpubadminscripts directory. Adsutil.vbs recognizes parameters that consist of a command action and parameters that apply to that command. This script is complex but can be a powerful tool.

A good way to get basic help for the IIS Administration Script Utility is to open a command window and run the script without parameters. Most documentation shows a call to adsutil.vbs prefaced with the cscript command, which signifies that the CScript environment must host this script. (For information about the difference between CScript and WScript, how to toggle the default host environment from the command line, and how to make the new environment setting permanent, see the Web-exclusive sidebar "Toggling the Scripting Host.") As with any .vbs file, you can use the filename to execute the file, and the file will run under the default scripting host, which means that the results will initially vary based on your scripting configuration. By default, a Windows system hosts scripts in the WScript environment. If you run adsutil.vbs in this environment, the script opens a series of dialog boxes to let you know that you must run adsutil.vbs with the CScript host and to let you change your default script hosting environment to CScript. The advantage of making this change is that you no longer need to type cscript at the beginning of each command when you use this utility.

Table 1, page 2, provides a list of the command parameters that adsutil.vbs accepts. I created this table based on the adsutil.vbs documentation that ships with IIS, which you can find at http://localhost/iishelp/iis/htm/adminsamples/adsutil.htm on your local server. A call to adsutil.vbs accepts one command from this table followed by the parameters appropriate for that command. Figure 1 shows the execution of a pair of calls to the IIS Administration Script Utility from the command line.

As the figure shows, I go to the installation directory for the IIS administration scripts to run adsutil.vbs. The first call to "get" a value passes a string representing both the path and the property name of the desired value. The second call in this figure uses the SET command. Notice that if the value to be set includes spaces or special characters, you must enclose those spaces or characters in quotation marks (""). The key's path (e.g., w3svc/1) uniquely identifies which branch of the metabase you're requesting. The path is the unique identifier to a specific entry in the metabase. Also, notice that both calls reference the property by name (e.g., servercomment). One of the few limitations of adsutil.vbs is that it requires the referenced property to have a name. However, if you use MetaEdit, you'll see that not all properties have names. You'll also see that, unfortunately, you can't manipulate a property name, even with MetaEdit.

One fact that might not be immediately obvious from Figure 1 is that the various commands you can use in a call to adsutil.vbs aren't necessarily the same commands you would use if you were attempting to script calls to the IIS Admin objects. Each key is associated with a specific type of IIS Admin object (e.g., w3svc/1 is an IIsWebServer object). Although the adsutil.vbs script exposes commands, these commands aren't the same as the methods you would use if you were scripting a call directly to the IIS Admin object. Rather, the adsutil.vbs commands are oriented around administrative actions. In fact, each adsutil.vbs command requires several lines of script to implement. The script determines the command, checks the parameters, then calls an internal function to carry out the requested task. In some cases, such as the SET command, these lines involve several calls to metabase object methods.

In contrast, some similar but separate commands that you can use with adsutil.vbs are actually calls to the same method on an IIS Admin object. A good example of such a set of similar commands is APPCREATEINPROC, APPCREATEOUTPROC, and APPCREATEPOOLPROC. These commands each make a call to the method AppCreate2 on the appropriate IIS Admin object (e.g., IIsWebDirectory). Notice in Table 1 that some commands, including these three, have a parameter list specifying that the key path must go all the way to the root directory. The reason for this long path is that the method AppCreate2 is part of only two types of keys that make up the metabase. (For more information about AppCreate2, go to http://msdn.microsoft.com/library/default.asp?url=/library/psdk/iisref/aore3ype.htm.) In addition, in IIS 4.0, adsutil.vbs doesn't support the command APPCREATEPOOLPROC. This command is a new feature of IIS 5.0, and Microsoft changed the call to create the process.

Before I leave adsutil.vbs, let me briefly mention how to use it to modify metabase settings on other computers in your domain. This use is another limitation of adsutil.vbs. To access the metabase, you need to be running under an account with the appropriate permission for the target machine, which means running with a Domain Administrator account. After you've entered a command and its parameters, you can append the —s:servername parameter. This parameterauses adsutil.vbs to use the specific named machine rather than the default localhost value that it usually uses in the path.

Mkwebdir and Other IIS Administrative Scripts
The adminscripts directory isn't limited to adsutil.vbs. Table 2 lists some of the other scripts in that directory and a description of their purpose. Unlike asdutil.vbs, which was designed to support many different actions, the other scripts are oriented toward a specific task, and their parameters tend to be related only to information associated with that task. Each script is designed to run within the CScript host and will provide a list of parameters to let the script run successfully.

Some scripts, such as pausesvr.vbs and contsvr.vbs, are reasonably straightforward; however, others, such as mkwebdir.vbs, are a bit more challenging. You can run each script without parameters or with the —help or —? parameters to obtain a brief explanation of what the script does and a listing of its optional parameters (designated by square brackets—[]) and mandatory parameters. In the case of mkwebdir.vbs, one optional parameter is —c, which signifies that the directory is to be created on a specific machine or machines. The reason this parameter is optional is that the script is specifically looking to find that —c string in the first parameter and, if it doesn't find it, expects to find the next parameter.

Figure 2 shows an execution of a call to mkwebdir.vbs to add a new virtual directory to the default Web site on the current machine. The parameter —w is the mandatory name of the Web site that will contain this new virtual directory. Ideally, the script expects the name of the Web site that matches the value for the servercomment directory. However, the script attempts to check the server bindings in case the entered name is based on the site URL. (The script won't accept more than one Web site name.)

Figure 2 also shows the —v parameter for this function. A string containing the name and path of the one or more virtual directories you want to create then follows this parameter. A comma separates each element; the first part of the command is a name, and the second part is a virtual directory.

The statement in Figure 2 places the parameter indicators for the two mandatory parameters (i.e., —w and —v) followed by the strings that represent the data. You use the same type of format for many of the other scripts, but most scripts have what's referred to as a relative config store path as the first parameter. This value is the same key path that adsutil.vbs uses. The path is relative because it doesn't include the computer name or "IIS://," which signifies a metabase reference to the ADSI objects as part of the path.

Another script that deserves mention because of a couple of its parameters is mkw3site.vbs. This script creates a new virtual Web site on your server. The two mandatory parameters are the root directory and server comment. However, the more interesting parameters are —SiteNumber and —DontStart. Although the —DontStart parameter is reasonably self-explanatory, using it reduces the number of tasks mkw3site.vbs attempts to perform and lets you run other scripts such as mkwebdir.vbs to customize your newly created Web site before using adsutil.vbs to start the site.

The —SiteNumber parameter is important because it lets you bypass the default incrementing of the instance ID associated with a Web site. This ability is especially important if you're migrating sites from one server to another. The instance ID of a site is part of the path to that site's metabase data. (This capability isn't available from Internet Services Manager—ISM.) If you're attempting to manage servers in an environment with multiple Web sites that span multiple servers, this parameter can help to simplify your management tasks.

The Next Step
Now that you've learned about the scripts that your IIS installation provides, the next step is to look at customization. This customization isn't so much the alteration of the scripts as the ability to create files that string together calls to these scripts in series to complete a set of related steps. In a future article, I'll show you how to string calls to create a Web site, assign access permissions, create virtual directories, and start the new site.

Tip: Here's a warning about the list of computers: For readability, there's a space between each computer name in the script's documentation, but the script doesn't account for spaces and will look for a computer with the name space_computer2 if you use spaces in the actual call.