Microsoft provides the IIS Admin Objects to make the task of programmatic administration easier. These objects are automation-enabled and are based on the ADSI. This means that any language that supports automation can access these objects and manipulate them. VBScript and JScript are both automation-enabled, and because both are included with IIS, you already have all the tools you need.
Using the IIS Admin Objects, you can develop an ASP page or any custom application and manipulate the metabase properties by accessing the correct objects.
Keeping in mind the structure of the metabase as described earlier in this chapter, you can use the IIS Admin Objects to manipulate and set the properties on a server-wide basis or on individual files or services. All you need to do is access the correct object by using the full path to that object starting with the root.
The IIS Admin Objects mirror the metabase object hierarchy, which you can review by looking at Figure 1. You will see how you can gain access to the required object by traversing the hierarchy.
Active Directory Service Interfaces (ADSI) provides you a standard syntax for dealing with the IIS Admin Objects. Using this syntax, you can gain access to the necessary configuration data. As mentioned previously, the IIS HTML-based administration tool uses these objects to perform remote configuration.
The metabase path references the IIS Admin Objects. If you want to reference the second Web Server on the computer named websrvone, you would use the full ADSI path, called the AdsPath, like this: IIS://websrvone/W3SVC/2.
The IIS Admin Objects implement the IADs interface, which is defined by the ADSI standard. As a result, the following functionality is implemented:
A method of retrieving the namespace properties
A path to the schema definition of an object
Identification information, such as name and type of object
A caching system
A method of setting and retrieving properties for a specific node of the metabase
A way of retrieving the path for an object's parent
Binding information for uniquely identifying object instances in a directory tree
ADSI Container Objects
ADSI Container Objects are the IIS Admin Objects that can contain other objects by implementing the IADsContainer interface.
The IIS Admin Objects classed as container objects are the IISComputer and IISWebVirtualDir objects. IISComputer contains IISWebService and IISFtpService as the two objects directly below IISComputer. IISWebVirtualDir can contain an IISWebDirectory object, an IISWebVirtualDir object, and an IISWebFile object.
The IADsContainer interface enables the following procedures to be performed in relation to containers and their objects:
Create objects in a container
Delete objects from a container
Provide a count of the number of objects in a container
Access the objects in the container
Enumerate the objects
The Create, Delete, and Count methods and the GetObject and _NewEnum properties support these functions, respectively.
An example of how to use each method follows:
CreateSet newObj = Object(KeyType, Name)
newObj is used to access the new object in the container.
Object is the name of an IIS object that is normally returned by the GetObject method, as shown in the code example that follows.
KeyType is the type of IIS Admin Object to create.
Name is the name for the new object.
Dim WebSrvObject, SrvObject
Set WebSrvObject = GetObject("IIS://celeron/W3SVC")
Set SrvObject = WebSrvObject.Create("IISWebServer", "5")
This code snippet will first return the name of the W3SVC object located on the computer named celeron and assign it to the WebSrvObject variable. The next line of code sets the SrvObject variable to be the newly created IISWebServer object number 5.
DeleteObject.Delete KeyType, Name
Object is the IIS Admin Object returned by the GetObject method.
KeyType is the type of IIS Admin Object to delete.
Name is the name of the IIS Admin Object to delete.
Set WebSrvObject = GetObject("IIS://celeron/W3SVC")
WebSrvObject.Delete "IISWebServer", "5"
This code snippet will delete the object that was created with the Create method used earlier.
CountThis is a property of the ADSI Container Object; it returns the number of objects in the container.
_NewEnumThis property will return an enumerator object that can be used by VBScript or JScript to retrieve the objects in the container using a For Each loop.
If the object that you are deleting is a part of an application, the AppDelete method will be called first to remove the application definition before the object is removed. Be sure that this is what you want to do before deleting the object.
As mentioned before, the metabase stores the configuration properties for IIS. By making use of the IIS Admin Objects, you can manipulate these properties to configure IIS, create new Web and FTP sites, assign permissions, and perform other configuration tasks.
The HTML-based administrative tool is a good example of the use of the IIS Admin Objects. This tool uses a Web browser interface for remotely administering IIS. You can use this tool to become familiar with the various tasks that can be accomplished with the IIS Admin Objects and the metabase properties.
You can create HTML-based applications that run in a Web browser to administer your IIS server in much the same way that IIS's HTML-based administration tool does.
Manipulating the Metabase
In order to gain access to the IIS Admin Objects in the metabase, you need to navigate a hierarchical structure using what is known as the AdsPath. The AdsPath uses a syntax that looks similar to a URL. The general syntax looks like IIS://[path], where path is used to indicate the directory path of the object you are trying to access.
An example of an AdsPath would be IIS://celeron/MSFTPSVC, which would provide access to the FTP service running on my server celeron. This can be considered the root object for the FTP service, and it contains all the other objects that are considered children or subobjects of this root object.
In order to work with the objects in code, you normally use the GetObject method to return the name of the object that you want to work with so that you can use this name in your code.
Listing 14.1 Sample Code for Returning ADSI Object Properties
<%@ LANGUAGE=VBSCript %> <HTML> <HEAD><TITLE> </TITLE></HEAD> <BODY> <% Dim WebSrvObject Set WebSrvObject = GetObject("IIS://celeron/W3SVC") %> <B>Web Service Name</B>....<%= WebSrvObject.Name %> <BR> <B>ADsPath</B>....<%= WebSrvObject.ADsPath %> <BR> <B>Class</B>....<%= WebSrvObject.Class %> <BR> <B>GUID</B>....<%= WebSrvObject.GUID %> <BR> <B>Parent</B>....<%= WebSrvObject.Parent %> <BR> <B>Schema</B>....<%= WebSrvObject.Schema %> <BR> </BODY> </HTML>
If you place this code into an .asp file and run it on your server, you will see a display similar to that shown in Figure 2.
Figure 2 Internet Explorer showing the six properties of the W3SVC ADSI Object.
As you can see, using the GetObject method returned the object necessary for me to access the properties for the W3SVC. This is a simple .asp file that merely displays the properties that are associated with the W3SVC object that was returned.
The first line of code declares a variable, WebSrvObject, that will be used to hold the object returned by the GetObject method. In this way, we can use the variable name to refer to the object when we access its properties instead of needing to use the full AdsPath every time we need a property.
In order to use the GetObject method or any .asp script that accesses the metabase on your Web server, you will need to access the .asp page using an administrative account. If you attempt to access the file without this, you will receive an error message stating that the server cannot open the page because permission has been denied for the GetObject method.
The easiest way around this is to assign the appropriate permissions to the InetPub directory. For example, I added the group Everyone to the users list in the Security settings for the InetPub directory and allowed full control of the directory. This does have one inherent security risk. If the server is a production server connected to the Internet, you can allow any user from the outside or inside to connect to the InetPub directory and run applications, modify or delete files, and even upload and run Trojan horse programs or viruses. If you decide to do this, try to set up on a test system first. When your scripts are working as you want them to, transfer them to a production server.
Alternatively, you can create a logon page that will require a user to provide a username and password to be authenticated on the server using the NTLM or basic authentication methods. This way, you are protecting your production server from being easily compromised. This will, however, create an extra step that you must go through in order to test your pages using the GetObject method.