Configuring IIS via code

In this day and age, Web applications have become the norm. We've even come to the point where many development projects involve Web applications that must be installed on multiple servers. But even if you don't build vertical Web applications, it's useful to have a configuration utility that can recreate a configuration via code. This might be for backup purposes, or for high volume environments like load balancing, where multiple servers need to be configured.

In order to accomplish this gracefully, you need to be able to configure the Web server programmatically, because the current crop of development tools do not provide that functionality. In this article, I'll demonstrate how you can configure Internet Information Server programmatically by using the Active Directory Service Interface (ADSI) and the IIS Admin objects to create an installation application. I'll show a Visual FoxPro class that provides several of the key elements needed for configuring a Web application, so you can build setup Wizards or preset setup scripts.

How do we configure a Web server?

When you build a Web application there are many components that make up that application. You have the data engine with its data files, whether SQL Server, another backend database, Visual FoxPro or Access. There are the actual application binary files - the EXE or DLL of the application, plus any support files. If you're building a purely script-based application, you won't have those binary application files. In a Web application, there are HTML or scripted HTML (plain HTML or ASP, JSP, Cold Fusion or Web Connection script) files that must be deployed in a Web directory.

Notice that in most Web applications, the HTML/script content in the Web directories will be separate from the binary and data content of the application. This means that if you distribute a Web application, you typically install into two locations: the application path and the Web path.

The Web path requires more work than a traditional application path, because it's sitting on the Web server and needs to be recognized as a Web path. It also needs certain permissions set so that the Web server can access the files correctly.

A typical Web application needs to perform the following configuration tasks:

Find the Web site the user wants to install onIIS allows you to install multiple Web sites on the same machine. In particular, ISPs will have a large number of sites on a single machine, so don't necessarily assume that the user wants to install on the default Web site.

Install and/or configure the Web siteIf you're building a vertical Web application, it's likely that you want to install the application on a completely separate Web site as opposed to just a directory under an existing site. You'd create the Web site and then also configure it with performance and security settings. In some cases, you may also change some of these settings for non-dedicated Web sites.

Create a Virtual Directory for your applicationRegardless of whether your application runs on a dedicated site or under an existing site, you'll need to set up a virtual directory for it. Virtual directories allow you to isolate your application from the rest of the site and configure it independently. Once a virtual directory is created, you need to configure its security settings.

Create script mapsIf your application runs a custom development tool such as Web Connection, you may also want to set up a custom script map that routes to a specific handler ISAPI DLL. The script map provides a custom extension to your application and, in some cases, lets you hide clues about the tool you're using behind the scenes (which can give you more security against hackers).

The IIS Admin Objects

The IIS Admin Objects make it possible to configure the above tasks and more relatively painlessly. The IIS Admin Objects are in a COM object that can connect you to any resource listed in the IIS metabase, which is used to store all the IIS configuration settings. The IIS Admin Objects contain an Active Directory Service Interface (ADSI) that's specific to IIS and uses the common ADSI interface syntax. This includes a handful of method calls and properties, extended by the properties that the actual service (in this case the IIS Admin provider) exposes.

This is best illustrated by an example. The following code accesses the default Web site and retrieves a few of the properties via the IIS Admin objects:

This short snippet connects to the root directory of the default Web site and reads a few settings. However, most configuration settings of value are found at the virtual directory level. The hierarchy of the IIS Admin Objects starts with:

IISWebService

Contains many settings similar to the virtual directory settings, but doesn't let you control them. This object contains many performance options, however. Typically you'll use this only for very specific things. The Web service is W3SVC in the GETOBJECT moniker string above.

IISWebServer

The individual Web sites which can be enumerated. The 1 in the GETOBJECT moniker above identifies the site in question. Sites are numbered sequentially and must be enumerated in order to retrieve a friendly name (I'll show an example of that shortly). This object also serves mainly as a performance and high level settings place holder. Although it has many of the same settings as IISWebVirtualDir, many of these settings don't do anything. The performance options do, however.

IISWebVirtualDir

The virtual directories, including the ROOT directory, contain most of the important settings that you need to configure a Web site.

As a general rule, you want to set any inherited settings at the lowest possible level. So, setting execute rights should be done at the virtual level and not at the Web server level. Performance settings that are available both in the WebService and WebServer objects should be made on the WebServer object. For a detailed list of properties available for each of these objects, see the MSDN documentation for the IIS Admin Objects. A Web link to this topic is provided at the end of the article.

Looking at the example above, you can see that you can read and write settings simply by assigning values to the appropriate property. But, make sure that you call SetInfo() to actually write the settings into the IIS metabase. Until you do, the settings are cached and don't change the operation of IIS. Once SetInfo() has been called, the settings are written and take effect immediately.

By: Rick Strahl

Rick Strahl is president of West Wind Technologies in Maui, Hawaii. The company specializes in Web and distributed application development and tools, with focus on Windows Server Products, .NET, Visual Studio, and Visual FoxPro. Rick is the author of West Wind Web Connection, West Wind Web Store, and West Wind HTML Help Builder. He’s also a C# MVP, a frequent contributor to magazines and books, a frequent speaker at international developer conferences, and the co-publisher of CoDe Magazine. For more information please visit his Web site at www.west-wind.com or contact Rick at rstrahl@west-wind.com.

rstrahl@west-wind.com