About IIS ADSI Objects

Article
09/14/2006

The IIS ADSI objects are COM Automation objects that you can use within command-line scripts, ASP pages, or custom applications to change IIS configuration values stored in the IIS Metabase. For example, instead of using IIS Manager, you can write a script to set permissions for the AppRoot, LogType, and ConnectionTimeout properties in the metabase.

This topic includes the following sections:

Relationship Between ADSI and the Metabase
Properties
Methods
Inheritance
Security
Extending the IIS ADSI Schema

Relationship Between ADSI and the Metabase

Each IIS ADSI object corresponds to a key in the Metabase Schema. For example, the IIsWebServer (ADSI) ADSI object corresponds to the IIsWebServer collection key in the metabase schema file, as in the following line of code in MBSchema.xml:

  <Collection InternalName="IIsWebServer" 
        MetaFlagsEx="NOTABLESCHEMAHEAPENTRY | CONTAINERCLASS" 
        MetaFlags="HASUNKNOWNSIZES" 
        ContainerClassList="IIsObject,IIsCertMapper,IIsFilters,IIsWebVirtualDir" 
        InheritsPropertiesFrom="MetabaseBaseClass">

The IIS ADSI objects and the keys in the metabase schema file describe only the structure of your IIS configuration, in the same way that the schematic for a building describes the structure of a building. IIS uses the metabase schema as a guide to build your Metabase Configuration File, add Web sites and virtual directories, and make other configuration changes as your Web server grows. The metabase configuration file contains instances of the keys in the metabase schema file. For example, on a default installation of IIS 6.0, your metabase configuration file contains one instance of the IIsWebServer key for your default Web site, as in the following lines of code in MetaBase.xml:

  <IIsWebServer  Location ="/LM/W3SVC/1"
        AppPoolId="DefaultAppPool"
        DefaultDoc="Default.htm,Default.asp,index.htm,iisstart.asp,Default.aspx"
        SecureBindings=":443:"
        ServerBindings=":80:"
        ServerComment="Default Web Site"
        ServerSize="1">

When you use an IIS ADSI object to access data currently in the metabase configuration file, you are creating an instance of that IIS ADSI object and filling the object properties with current data. For example, when using the IIsWebServer ADSI object to connect to the default Web site on your Web server, you create an instance of the IIsWebServer object whose properties, like ServerComment, contain the information seen above. The following VBScript code creates an instance of the IIsWebServer ADSI object that is connected to the default Web site on a machine named MachineName:

  Set IIsWebServerObj = GetObject("IIS://MachineName/W3SVC/1")

Because modifying an IIS ADSI Object property changes the value of the corresponding metabase property, you can configure individual elements of IIS, such as the local machine (LM,) using the IIsComputer object; the FTP server (MSFTPSVC) using the IIsFtp* objects; the Web server (W3SVC) using the IIsWeb* objects; the Network News server (NNTPSVC) using the IIsNntp* objects; and the Simple Mail server (SMTPSVC) using the IIsSmtp* objects.

Properties

Each IIS ADSI object contains two sets of properties: one read-only set that all ADSI objects must contain, and one set exclusively for IIS that corresponds to the properties in the metabase schema.

For example, the Name and AdsPath properties of the IIsWebServer object are two of the six read-only Windows ADSI object properties that all ADSI objects must contain. The LogType, and ConnectionTimeout properties are two of the 51 possible properties that can be set at the IIsWebServer level. These properties are seen in the metabase schema file under the <Collection> key:

  <Property InheritsPropertiesFrom="IIsConfigObject:LogType"/>
<Property InheritsPropertiesFrom="IIsConfigObject:ConnectionTimeout"/>

These properties may not show up in the metabase configuration file unless they have been specifically set at that level. If they do not show up, they may be inherited from the parent key.

Methods

Some IIS ADSI objects contain three sets of methods: one set that creates and deletes new objects, one set that changes properties of ADSI objects, and one set that exclusively relates to the purpose of the ADSI object in which the methods are found.

For example, the Create method is one of the five Windows ADSI container object methods that all ADSI objects contain. With them, you can create and delete new instances of ADSI objects, get references to child objects, and move object instances around. The following VBScript code creates a new instance of the IIsWebVirtualDir object contained within another IIsWebVirtualDir object, thereby creating a new virtual directory called NewVDir in your Default Web Site:

  Set IIsWebVDirRootObj = GetObject("IIS://MachineName/W3SVC/1/Root")
Set IIsWebVDirObj = IIsWebVDirRootObj.Create("IIsWebVirtualDir", "NewVDir")

The Get, Put, and SetInfo methods are three of the eight Windows ADSI object methods that all ADSI objects contain. With them, you can get the value in a property, set it to something else, and then save the info to the metabase. The following VBScript code continues from the last code to set some necessary properties on the newly created virtual directory:

  IIsWebVDirObj.Put "Path", "C:\NewContent" 
IIsWebVDirObj.Put "AccessRead", True
IIsWebVDirObj.Put "AccessScript", True

The IIsWebDirectory.AppCreate2 (ADSI) method of the IIsWebVirtualDir (ADSI) object relates only to creating applications on virtual directories and Web directories. The following VBScript code continues from the last code to create an application on your new virtual directory, set a property that is necessary to the application, and finally save the new settings in the metabase with the SetInfo Windows ADSI object method:

  IIsWebVDirObj.AppCreate2 1
IIsWebVDirObj.Put "AppFriendlyName", "NewApp"
IIsWebVDirObj.SetInfo

Other examples of methods that exclusively relate to the object that contains them are the methods of the IIsComputer (ADSI) ADSI object. Methods such as IIsComputer.Backup (ADSI) and IIsComputer.Restore (ADSI) are used to protect your metabase from potentially harmful changes. It is recommended that you always back up your metabase configuration file before making any changes. The following VBScript code backs up the metabase configuration file to a file called BeforeChanges.MD0, and backs up the metabase schema file to a file called BeforeChanges.SC0. These files are stored in your systemroot\System32\Inetsrv\MetaBack directory.

  Dim IIsComputerObj, iFlags 
' Create an instance of the IIsComputer object
Set IIsComputerObj = GetObject("IIS://janetfi-32") 
' Set flags to save the metabase first and force a backup even if the save fails. 
iFlags = (MD_BACKUP_SAVE_FIRST or MD_BACKUP_FORCE_BACKUP) 
'Backup to next available version number. 
IIsComputerObj.BackupWithPassword "BeforeChanges", MD_BACKUP_NEXT_VERSION, iFlags, "MyP@ssWOrd"

Inheritance

Because of the hierarchical structure of the metabase and its property inheritance feature, you can easily configure properties for a single file, a single server, all Web servers, all FTP servers, or the common properties of many other groups of objects.

Security

Only server administrators are permitted to change the values in the metabase through ADSI. If you are using ADSI in command-line scripts, note that they work only when run by an administrator. If you are using ADSI in a compiled program, set the account of the application to an administrative account. For increased security, it is recommended that you set access control on your scripts and compiled administrative programs to restrict access to the Administrators group. See "Access Control" in Windows Help for more information.

If you are using ADSI in an ASP page to configure the metabase, you must disable anonymous access to the Web application that contains the ASP page. It is recommended that you create a server or directory for your administrative ASP files and set the authentication method to use Integrated Windows authentication for the server or directory. For security purposes, out-of-process Web applications cannot access the metabase unless WAMUserName is recognized as an administrator; however, this is not a recommended configuration. As an alternative, change the identity of the specific out-of-process package to some other account identity, and give only that account administrative access to the metabase. This method introduces less potential risk, but it must be implemented for each out-of-process package.

Important It is recommended that you do not make the IWAM_machinename an administrator, unless special circumstances require you to. Making the IWAM_machinename an administrator means that anyone accessing your server through an out-of-process Web application has administrative privileges on your machine.

Extending the IIS ADSI Schema

If you find that no existing ADSI object class meets your management needs, you can extend the IIS ADSI schema. Extending the IIS ADSI schema is a complex operation. Consider your needs carefully, and assess whether an extension is really necessary.

For more information on extending the IIS ADSI schema, see ADSI Extensibility for IIS.