Using the IIS 7.0 Managed Configuration API

  • Article

More than a year ago I wrote about Microsoft.Web.Administration.dll and how it was a new API we were creating for managed code developers to be able to easily set any configuration settings of IIS, however I purposely ignored the configuration part of the API.

Later I talked about the way configuration was organized in IIS 7.0 and how configuration files inherited and worked.

Recently I was asked about some samples on how to modify IIS configuration and decided it was about time to talk about the configuration part of Microsoft.Web.Administration.

The first thing to really emphasize is that Microsoft.Web.Administration in a way has two different ways of reading configuration:

  1. Run time: This is a read-only version of configuration that is meant to be used when running inside a worker process in IIS. It is exposed through a class called Microsoft.Web.Administration.WebConfigurationManager and its GetSection() method with several overloads. Since this blog is about changing configuration I will not be mentioning this API, but suffice to say, it works the same except you get a read-only section.
  2. Design time: This API is our management story for modifying configuration from managed code, it is exposed through the class ServerManager and several of its methods listed below:

public sealed class ServerManager : IDisposable {

    // Note: some properties and methods were ignored since I'll focus on only these

    public void CommitChanges();

public void Dispose();

public Configuration GetAdministrationConfiguration();

public Configuration GetApplicationHostConfiguration(...);

public Configuration GetRedirectionConfiguration(...);

public Configuration GetWebConfiguration(...);

public static ServerManager OpenRemote(string serverName);
}

Whenever you work with the configuration system in IIS you need to:

  1. Figure out which section you want to modify

    The entire configuration in IIS is organized in sections inside configuration files. Sections are composed of elements, attributes, collections and potentially even methods. If you want to know what is the section you are looking you can search it in %windir%\System32\Inetsrv\Config\schema which is the folder where we place all the "schema" files that entirely describe the configuration in IIS.

  2. Figure out for which object you want to manage

    The configuration systemin IIS 7.0 is distributed and as such each child object inherits the configuration of its parent, so for example an application inherits the configuration of the site and the site inherits configuration from the server. So now you need to decide which objects you want to manage, for example, do you want to enable Windows Authentication for the entire server or do you only want to enable it for a particular site or application.

  3. Determine in which place you want to make the change

    As the previous bullet mentions the configuration system is distributed so now you can actually make the changes in different levels for the same object, for example you can modify applicationHost.config with a locationPath "Default Web Site" or you can obtain the same behavior by modifying a web.config file inside wwwroot directory. The concept that really impacts this decision is configuration locking since based on the settings that the server administrator has configured it might be invalid to set authentication in the web.config and might only be possible to set it in applicationHost.config.

OK, after all that talking lets go to the some actual examples and apply the 3 steps above.

All the code below assumes you have added a reference to Microsoft.Web.Administration.dll (located at %windir%\system32\inetsrv\) and that you are adding a "using Microsoft.Web.Administration;" at the top of your C# file.

Enable Directory Browsing for Default Web Site

  1. Looking into system32\inetsrv\config\schema\IIS_Schema.xml you will find that the correct name of the section I'm looking for is system.webServer/directoryBrowse
  2. I only want to modify Default Web Site
  3. Since I now that IIS by default is not locked then I'll make the change directly in the web.config of the site so that when you XCopy my site to another server it remains working the same way.

Code:

    using (ServerManager manager = new ServerManager()) {

Configuration webConfig = manager.GetWebConfiguration("Default Web Site");

      ConfigurationSection directoryBrowseSection =

      webConfig.GetSection("system.webServer/directoryBrowse");

      directoryBrowseSection.SetAttributeValue("enabled", true);

      manager.CommitChanges();

    } 

The code uses ServerManager to get the web.config of the web site and then queries the directoryBrowse section and sets the attribute 'enabled' to true. If you open IIS_Schema.xml you will see that this section defines the 'enabled' attribute as a Boolean.

<sectionSchema name="system.webServer/directoryBrowse">
  <attribute name="enabled" type="bool" defaultValue="false" />
  ...
</sectionSchema>

As you can see this API offers a loosely typed object model to ready and modify configuration, with the most important objects being Configuration, ConfigurationElement and ConfigurationAttribute.

Adding a Handler for the application MyApp underneath Default Web Site

  1. Looking into system32\inetsrv\config\schema\IIS_Schema.xml you will find that the correct name of the section I'm looking for is system.webServer/handlers
  2. I only want to modify Default Web Site/MyApp
  3. In this example let's actually modify applicationHost.config.

Code:

    using (ServerManager manager = new ServerManager()) {

Configuration webConfig = manager.GetApplicationHostConfiguration();

      ConfigurationSection handlersSection =
          webConfig.GetSection("system.webServer/handlers", "Default Web Site/MyApp");

      ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();

      ConfigurationElement handlerElement = handlersCollection.CreateElement();

      handlerElement.SetAttributeValue("name", "MyHandler");
      handlerElement.SetAttributeValue("path", "*.myhandler");
      handlerElement.SetAttributeValue("verb", "GET");
      handlerElement.SetAttributeValue("type", "CarlosAg.IIS.Samples.MyHandler");

      handlersCollection.Add(handlerElement);

      manager.CommitChanges();
    } 

In this case the handlers Section has a default collection which is where we want to add our handler. For that we use the CreateElement() method to get a new element that we can set the attributes and then add it.

Removing our Handler

  1. Same system.webServer/handlers
  2. Same Default Web Site/MyApp
  3. Same applicationHost.config.

Code:

    using (ServerManager manager = new ServerManager()) {

Configuration webConfig = manager.GetApplicationHostConfiguration();

      ConfigurationSection handlersSection =
              webConfig.GetSection("system.webServer/handlers", "Default Web Site/MyApp");

      ConfigurationElementCollection handlersCollection = handlersSection.GetCollection();

foreach (ConfigurationElement handlerElement in handlersCollection) {

        if (String.Equals((string)handlerElement.GetAttributeValue("name"), "MyHandler", StringComparison.OrdinalIgnoreCase)) {
handlersCollection.Remove(handlerElement);
break;
        }
}

manager.CommitChanges();

    }

Unfortunately currently there is no way to search collections so your only option is to iterate through elements and find the match you are looking for, in this case I'm matching by the name and then removing it from the collection.

Hopefully that should give a good initial steps on how to start working with configuration using Microsoft.Web.Administration, there are several other options I'll be mentioning in other post on how to lock configuration, how to set metadata, how to enumerate configurations and how to do much more advanced stuff for the few developers that will actually need advanced control of IIS configuration.