The IIsComputer Object | Windows NT/2000 ADSI Scripting for System Administration

The IIsComputer Object

The IIsComputer object exists at the top of the IIS Metabase hierarchy. In the Internet Service Manager snap-in for the MMC, this object can be presented graphically by right-clicking the name of the server and choosing Properties.

Using the IIsComputer interface, you can programmatically manage Metabase backups , throttle server bandwidth globally across all Web and FTP sites, and manage the default MIME-type entries for the server.

Backing Up the IIS Metabase Using Visual Basic

Before you begin programmatic administration of an IIS server, it is a very good idea to force a backup of the Metabase just in case you do something you might regret .

In general, the following syntax is used to perform a backup of the IIS Metabase:

 IIsComputerObj.Backup  BackupLocation, BackupVersion, BackupFlags

The BackupLocation parameter specifies the name of the file that will be stored in the %SystemRoot%\System32\Inetsrv\Metaback directory.

Using the BackupVersion parameter, you can specify whether you wish to create a new backup file or simply replace the highest version backup file in the directory. The BackupVersion parameter can be one of the following flags:

Flag	Description
MD_BACKUP_HIGHEST_VERSION	This flag replaces the highest backup version for the backup specified in the `BackupLocation` parameter.
MD_BACKUP_NEXT_VERSION	This flag creates a Metabase backup using the next available version number.

The BackupFlags parameter specifies how the backup should be performed and can be set to one of the following flags:

Flag	Description
MD_BACKUP_SAVE_FIRST	This flag performs a SaveData operation before the backup.
MD_BACKUP_FORCE_BACKUP	This flag performs the backup regardless of a failed MD_BACKUP_SAVE_FIRST operation.
MD_BACKUP_OVERWRITE	If there is an existing backup that is the same version as the one that is about to be saved, this flag overwrites the existing backup.

Armed with this background knowledge, you can now begin a backup of the IIS Metabase from Visual Basic, using the following code:

 Dim IIsComputer As IADs Dim Flags As Long Dim TargetComputer as String TargetComputer = "  Target_Server_Name  " Flags = (MD_BACKUP_SAVE_FIRST Or MD_BACKUP_FORCE_BACKUP) Set IIsComputer = GetObject("IIS://"&TargetComputer) IIsComputer.Backup "MyBackup10", MD_BACKUP_NEXT_VERSION, Flags

Enumerating Existing Backups Using Visual Basic

To verify that the backup did indeed occur, you can enumerate all backups using the EnumBackups method of the IIsComputer interface.

Consider the following Visual Basic code to enumerate all existing Metabase backups:

 On Error Resume Next Dim IIsComputer As IADs Dim TargetComputer As String Dim Version, Index, TermCond As Integer Dim Location As Variant Dim UTCDate As Variant TargetComputer = "  Target_Server_Name  " Set IIsComputer = GetObject("IIS://" & TargetComputer) Do While TermCond <> 1   IIsComputer.EnumBackups ", Index, Version, Location, UTCDate   If Err.Number <> 0 Then     Exit Do   End If   Debug.Print Location &" Version: "& Version &" " &UTCDate   Index = Index + 1 Loop

Restoring an Existing Metabase Backup Using Visual Basic

After you have completed a backup of the IIS Metabase, you can practice the procedure to restore the settings using programmatic methods . To perform this task, call the Restore method of the IIsComputer interface with the backup location and desired version information passed as arguments.

Consider the following Visual Basic code to help you restore the IIS Metabase after a successful backup:

 Dim IIsComputer As IADs Dim TargetComputer As String Dim BackupLocation As String TargetComputer = "  Target_Server_Name  " BackupLocation = "Backup_Location_On_Target_Server" Set IIsComputer = GetObject("IIS://" & TargetComputer) IIsComputer.Restore BackupLocation, MD_BACKUP_HIGHEST_VERSION, 0

Tip

To apply changes to the Metabase after a restore, you may have to reboot the server.

Deleting an Existing Metabase Backup Using Visual Basic

After testing the functionality of programmatic Metabase backup methods, you may want to clean up your server by removing all old backup files.

Use the DeleteBackup method of the IIsComputer object in Visual Basic to delete an existing Metabase backup file, as follows :

 Dim IIsComputer As IADs Dim TargetComputer As String Dim BackupLocation As String TargetComputer = "  Target_Server_Name  " BackupLocation = "Backup_Location" Set IIsComputer = GetObject("IIS://" & TargetComputer) IIsComputer.DeleteBackup BackupLocation, MD_BACKUP_HIGHEST_VERSION

Tip

Using the previous code, the system will delete the last backup performed in the specified backup location. If combined with the enumeration example, you can easily delete all existing backups programmatically.

Additionally, you can replace the MD_BACKUP_HIGHEST_VERSION flag with the actual version number of a backup if you want to remove only a specific Metabase backup.

Manipulating Maximum IIS Network Bandwidth

As shown in Figure 8.2, IIS allows you to limit the bandwidth allocated to the File Transfer Protocol (FTP) and Web services on the IIS server using the MaxBandwidth property of the IIsComputer interface. This can be especially useful when a server, such as a departmental intranet server, also performs several duties , such as acting as a file server or mail server.

Note

Limiting the bandwidth can also be helpful in development environments. Usability testers and developers can obtain rough estimates of the effect of a slow Wide Area Network (WAN) link on the overall client experience when navigating the production Web site. All too often, Web designers create incredibly creative, aesthetically pleasing sites but forget that some visitors will be viewing the site at much slower connection speeds than the LAN speed connection used for development.

Figure 8.2. IIS Server global properties.

graphics/08fig02.gif

Querying MaxBandwidth Using Visual Basic

Use the following Visual Basic code to view the current running configuration for the MaxBandwidth property:

 Dim IIsComputer As IADs Dim TargetComputer as String Dim RetVal as Long TargetComputer = "  Target_Server_Name  " Set IIsComputer = GetObject("IIS://" & TargetComputer) RetVal = IIsComputer.MaxBandwidth Debug.Print RetVal

If bandwidth throttling is not currently in use, a value of “1 will be returned.

Tip

The value returned is in bytes. If you want to view the information in KB (as the Internet Service Manager shows it), divide this value by 1024 before displaying it.

Setting a New Value for MaxBandwidth Using Visual Basic

Using the following Visual Basic code, you can specify a new value in bytes for the bandwidth throttling setting for an IIS server:

 Dim IIsComputer As IADs Dim TargetComputer as String Dim NewValue as Long TargetComputer = "  Target_Server_Name  " NewValue = New_Throttle_Value_In_Bytes Set IIsComputer = GetObject("IIS://" & TargetComputer) IIsComputer.MaxBandwidth = NewValue IIsComputer.SetInfo

Warning

Although the Internet Service Manager dialog box shows that the change was made to the Metabase, you must cycle the Web publishing service in order for the change to take affect. To cycle the Web service using programmatic methods, follow the service start and stop procedures found in Chapter 6, "Programmatic Computer and Service Manipulation."

MIME Mapping Management

Using the Internet Service Manager MMC snap-in or programmatic methods, you can modify the MIME types sent to browsers in HTTP headers. IIS allows the global definition of MIME types for the server, but also allows individual sites to override the settings if a particular site requires a MIME type that differs from the global setting.

Viewing the List of Current Server-Defined MIME Type Mappings Using Visual Basic

Using the following Visual Basic code, you can enumerate the MIME types inherited by all Web sites:

 Dim IIsComputer As IADs Dim TargetComputer as String Dim MimeMapping as Variant TargetComputer = "  Target_Server_Name  " Set IIsComputer = GetObject("IIS://" & TargetComputer & "/MimeMap") Debug.Print "Registered File Types:" For Each MimeMapping in IISComputer.MimeMap    Debug.Print "Extension: " & MimeMapping.Extension & " MIME Content Type: "& MimeMapping.MimeType Next

Adding a New Server-Defined MIME Mapping Using Visual Basic

If you plan to implement a new document type that you want to associate with an application for all sites on a particular server, you can add a new MIME type at the server level.

Use the following Visual Basic code to create a new MIME mapping to be used by all sites on the IIS server:

 Dim IIsComputer As IADs Dim TargetComputer As String Dim MimeMapping As Variant Dim NewMimeMapping As Variant Dim MimeExtension As String Dim MimeType As String Dim i As Integer TargetComputer = "  Target_Server_Name  " MimeExtension = "  New_MIME_Extension  " MimeType = "  New_MIME_Type  " Set IIsComputer = GetObject("IIS://" & TargetComputer & "/MimeMap") NewMimeMapping = IIsComputer.GetEx("MimeMap") i = UBound(NewMimeMapping) + 1 ReDim Preserve NewMimeMapping(i) Set NewMimeMapping(i) = CreateObject("MimeMap") NewMimeMapping(i).MimeType = MimeType  NewMimeMapping(i).Extension = MimeExtension IIsComputer.PutEx ADS_PROPERTY_UPDATE, "MimeMap", NewMimeMapping IIsComputer.SetInfo

Tip

To use the preceding code to create a new MIME type for all files with the extension .TEE with Microsoft Word, simply assign the MimeExtension variable to ".TEE" and the MimeType variable to " application/msword ".

Removing a Server-Defined MIME Mapping Using Visual Basic

Although it's easy to place objects into an array, it's a bit trickier to delete them. When you think of deleting an object, you typically specify its name in some form of delete operation. However, when manipulating objects in an array, you have no way of specifically identifying individual objects within the array.

Early in life, you learned that if you did not want to include someone in an activity, it was far easier to fail to tell her where you were going rather than to specifically state that you didn't want her company. This kindergarten principle can be applied to programming efforts: If you want to delete a MIME type, you can create a new array that resembles the old one, but without the MIME type you want to delete, using a conditional to delete the mapping.

Warning

If you have not made a recent backup of the Metabase, you may want to do so before running this code. If you do not want to use the programmatic methods described earlier, you can also use the Internet Service Manager to create the backup. No matter how you intend to perform the backup, creating a backup of the Metabase before running this procedure is strongly recommended.

The following Visual Basic code combines parts of the MIME type enumeration function you examined earlier (in the section "Viewing the List of Current Server-Defined MIME Type Mappings Using Visual Basic") as well as the MIME type definition code from the last example:

 Dim IIsComputer As IADs Dim TargetComputer As String Dim MimeMapping As Variant Dim MapToDelete As String Dim NewMimeMapping As Variant Dim i As Integer MapToDelete = "  Extension_To_Delete_From_MIME_Map  " TargetComputer = "  Target_Server_Name  " Set IIsComputer = GetObject("IIS://" & TargetComputer & "/MimeMap") NewMimeMapping = IIsComputer.MimeMap For Each MimeMapping In IIsComputer.MimeMap     If MimeMapping.Extension <> MapToDelete Then         ReDim Preserve NewMimeMapping(i)           Set NewMimeMapping(i) = CreateObject("MimeMap")         NewMimeMapping(i).MimeType = MimeMapping.MimeType         NewMimeMapping(i).Extension = MimeMapping.Extension         i = i + 1     End If Next Dim MimeItem As Variant For Each MimeItem In NewMimeMapping     Debug.Print MimeItem.MimeType Next IIsComputer.PutEx ADS_PROPERTY_UPDATE, "MimeMap", NewMimeMapping 'IIsComputer.SetInfo

Note

Notice that the last line is commented out. Before you write your new array to the namespace, make absolutely sure that the new array exists and is filled with all previous data (less the extension you specified to be deleted). Check that a list of extensions is returned in the immediate window before writing the new array to the namespace.

After you have verified your code is working as expected, remove the For Each loop just before the commented line and delete the apostrophe before the IIsComputer.SetInfo line to allow the changes to be written to the IIS Metabase.

Warning

If an error occurs that results in an empty array being written to the Metabase, you will lose all defined MIME types and will have to restore the Metabase using the restore procedure described previously.

Top