Use Scripts to Configure IIS

Administering IIS typically involves reading and configuring settings and performing various tasks such as backing up IIS. In "How to Use a Script to Access and Read the Metabase," October 2002, InstantDoc ID 26261, I described how to use Microsoft Active Directory Service Interfaces (ADSI) scripts to perform an important IIS administrative task—reading the metabase. In this article, I explore another important IIS administrative task: writing settings to the metabase. With simple script examples and straightforward, applied discussion, I demonstrate how to use ADSI scripts to configure IIS. If you're unfamiliar with the IIS metabase, ADSI scripting, or IIS Admin Objects, be sure to read "How to Use a Script to Access and Read the Metabase."

ADSI scripts can improve IIS administrative operations in several ways. Scripts let you

Before you attempt to use scripts to configure the metabase, be sure to back up the metabase because an improper metabase configuration can cause IIS operations to fail. In an upcoming article, I'll explain how to use a script to back up the metabase, but in the meantime, you can perform the backup from the IIS console. Another important consideration when using scripts to configure the metabase is that you can't use ADSI scripts to perform any administrative task that you can't complete using other means. ADSI uses user credentials to connect to the metabase; all the script examples in this article use a function that connects to the metabase in the context of the currently logged-on user.

Configure Keys in the Metabase
IIS stores configuration settings in metabase keys. Before you attempt to configure a metabase key's attributes, you need to consider the attribute's data type because you don't configure all attributes in the same way. For example, configuring the HTTPErrors setting, a List data type attribute that can have many values, requires a different script procedure than configuring the ServerAutoStart setting, a Boolean data type attribute that has just one value—True or False. Web Table 1 (http://www.windowswebsolutions.com, InstantDoc ID 26932) shows the data types found on a Windows XP­based computer running IIS 5.1. (These data types apply to Windows 2000 also.) Note that the Integer data type in Web Table 1 includes both 32-bit and 64-bit data types.

The table's Totals column, and thus the distribution of metabase keys, varies depending on the IIS version and the metabase key to which the script binds. However, within the IIS metabase hierarchy, the Boolean, Integer, and String data types occur most frequently. By running the script IISAtt_ReadDataTypes.vbs, which Web Listing 1 shows, you can determine the distribution of data types for your IIS implementation. Also, "How to Use a Script to Access and Read the Metabase" contains a script that lists each metabase key's attributes along with its data type and value (if any).

You use similar methods to configure all Boolean, Integer, and String data types. See the Web sidebar "Configure Boolean, Integer, and String Data Types" (http://www.windowswebsolutions.com, InstantDoc ID 26985) for a description of a script that demonstrates this configuration.

Configure List Data Types>
Boolean, Integer, and String data types represent approximately 80 percent of IIS data types. The next most common data type is List. The List data type contains zero or more items and can be multivalued (i.e., can store more than one value). Common List data type attributes on a computer running IIS 5.1 include

Configuring multivalued attributes is trickier than configuring single-valued attributes. First, you must consider whether you want to overwrite all existing values, append an entry to an existing list of values, delete one entry, or clear all entries. ADSI includes the IADs::PutEx method, which is designed for configuring multivalued attributes. PutEx can update all values, append a value, delete a value, or clear all values. Unfortunately, the IIS provider supports the PutEx method only for updating and clearing all values, so you need to jump through some scripting hoops to append to or delete values for this type of attribute.

To update, append, or delete values for multivalued attributes, you must know the String format for the attribute's values because you need to specify one or more values for the attribute in the script. For example, the String format of the ServerBindings attribute is IP address:port number: host header name. The first and third parameters, IP address and host header name, are optional, but you must use colons to delimit each parameter. The following strings are legal for the ServerBindings attribute:

To determine the String format of a particular IIS attribute, go to the Alphabetical Property List Web page in the Microsoft Developer Network (MSDN) Library at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/iisref/html/psdk/asp/apro1cms.asp and read the details about the attribute.

Update and Clear Values from List Data Types
Updating all values and clearing all values for List data types are the two simplest tasks to perform against this type of attribute, so let's start there. After completing these tasks, I show you how to use a little VBScript array manipulation to selectively delete and append values.

Updating a List data type attribute overwrites any existing values, so exercise caution when choosing a script to perform a simple update operation. IIS_ListDTs_Update.vbs, which Listing 1, page 14, shows, updates the ServerBindings attribute to contain the two values :80: and 192.168.3.67:100:Header1. The first value is common; the second value isn't. If you're modifying attribute values on a production system, make sure you know appropriate values for attributes before you use scripts to modify them.

The first line of callout A in Listing 1 defines the constant ADS_PROPERTY_UPDATE. This constant is the first parameter of the PutEx method that the script uses. The constant tells PutEx to update the value stored in the specified attribute. The remainder of callout A initializes four variables and binds to a metabase key. The first two variables, strADsPath and strKey, help build the binding string. The third variable, strAttribute, contains the attribute ServerBindings, which the script will update, and the fourth variable, strEntry, contains the values that the script will apply to the attribute. The script places the attribute's values in strEntry in an array because more than one value will be applied to this attribute. Each value is enclosed in quotes and followed by a comma.

The code at callout B in Listing 1 completes the process of updating the attribute and thus modifying the object in the local property cache. The PutEx method takes three parameters: the constant described in the previous paragraph, the name of the attribute to update, and the attribute's new value. Each parameter is followed by a comma. The last line of callout B saves the modified object back to the metabase. The code at callout C in Listing 1 reads back the attribute so that you can verify that the update was successful.

Clearing a List data type attribute is similar to updating one. The first line of the script IIS_ListDTs_Clear.vbs, which Listing 2 shows, declares the On Error Resume Next statement. This statement lets the script bypass an ADSI Property Not Found error that occurs later when the script attempts to read values from an empty attribute. From an ADSI perspective, an empty attribute is nonexistent and, therefore, absent from the local property cache. The constant E_ADS_PROPERTY_NOT_FOUND is set equal to the error code generated when ADSI can't find the attribute. The last line of callout A in Listing 2 defines the ADS_PROPERTY_CLEAR constant, which the PutEx method uses later in the script to clear an attribute's values.

The code at callout B in Listing 2 clears the attribute. The PutEx method requires three parameters to clear all of an attribute's values: the ADS_PROPERTY_CLEAR constant, the name of the attribute to clear, and the number 0. After PutEx clears the attribute, SetInfo commits the modified object to the metabase. The rest of the code at callout B verifies that the attribute was cleared by using the GetEx method to attempt to retrieve the attribute. If the retrieval doesn't return an attribute, the E_ADS_PROPERTY_NOT_FOUND error code appears, and you can infer that the attribute doesn't contain any values. If clearing the attribute was unsuccessful, the script displays the attribute's values.

Delete and Append Values from List Data Types
Deleting and appending values from List data types is a bit more complicated because the IIS provider doesn't support the ADS_PROPERTY_DELETE and ADS_PROPERTY_APPEND parameters of the PutEx method. Therefore, to use the IIS provider and the PutEx method to perform a delete operation, you must populate an array with any existing values, remove the specified item from the array, then use ADS_PROPERTY_UPDATE to replace the attribute's values. To perform an append operation, you must populate an array with any existing values, expand the array by one, add the new value to the array, then use ADS_PROPERTY_UPDATE to replace the attribute's values.

Listing 3 shows the script IIS_ListDTs_Delete.vbs, which deletes a value from the ServerBindings attribute. In this case, the value that the script attempts to delete is 192.168.5.5:200:SomethingNew, which the script stores in the strEntry variable. If the script can't find the value, it continues without an error. Note that case is important when you work with host headers: The host header SOMETHINGNEW is different from the host header SomethingNew. The IIS console also is case sensitive when you use it to attempt to delete an entry from ServerBindings. The final part of the script displays the contents of the ServerBindings attribute so that you can verify that, if the value was present, the script removed it. The array manipulation occurs at callout A in Listing 3. After retrieving the attribute's values and storing the values in the arrValue array (aka a collection), the script evaluates each value in the arrValue attribute. The values that don't match the entry you're attempting to delete are stored in the new array (i.e., arrValueMod). After the script populates the new array with the appropriate values, the script specifies the arrValueMod array variable as the last parameter in the PutEx method, which appears right after the end of callout A.

The script IIS_ListDTs_Append.vbs, which Listing 4, page 16, shows, appends a value to the ServerBindings attribute. The first part of the script should look familiar by now—the new code starts at callout A in Listing 4. After retrieving the attribute and storing its values in the arrValue array, the script checks the collection to see whether the new value is already present to ensure that the script doesn't add the same value to the attribute multiple times. If the value is present, the script informs the operator and quits; otherwise, the script continues, as callout B shows, by adding another position to the arrValue array while preserving the existing values it retrieved from the attribute. The script then adds the new value, which is contained in the strEntry variable, to the arrValue array. The PutEx method updates the attribute with the modified array and commits the changes to the metabase. The script then retrieves the attribute from the metabase and reads it back to the operator to verify that the update was successful.

Most of the Story
You now know how to configure approximately 90 percent of all metabase attributes. For the most common data types—Boolean, Integer, and String—you can use the Put and SetInfo methods. For the next most common data type, List, you can use the PutEx method to update and clear values. Using some array manipulation, you can also delete and append List data type attribute values. In a future article, I'll demonstrate how to use ADSI scripts to read and configure attributes stored as more complex data types, such as MimeMap and AdminACL.