IIS7 Managed Extensibility: Extending Configuration

I showed you the HttpModule on which this walkthrough is based on in the last post. This module is always active once it is registered and changes the Server header to a hardcoded value. It would be nice if the value and the ‘enabled’ status could be read from a configuration file. In this post I will show you the bits and pieces you have to do to add a new configuration section and make this section available to the IIS7 command line configuration tool and the configuration API.

OK – so first of all you should have an idea how your configuration section looks like, I chose the following design (inside of system.webServer):

<serverHeader enabled=true value=http://www.leastprivilege.com />

To make the IIS configuration system “understand” this config section, you have to provide a schema file. This file describes the layout of the section and things like required values, default values, value boundaries and more. Unfortunately there is no documentation of the XML vocabulary used – but if you look at windowssystem32inetsrvconfigschema – you can inspect the schema used for the built-in section and get an idea of the options you have. The XML schema file for our section looks like this:


  <sectionSchema name=system.webServer/serverHeader>

    <attribute name=enabled type=bool defaultValue=false />

    <attribute name=value type=string defaultValue=http://www.leastprivilege.com />



Copy this file to the above location. The next step is to register the configuration section in applicationHost.config (windowssystem32inetsrvconfig). Search for the system.webServer section group and add a new section underneath, like this:

<sectionGroup name=system.webServer>

  <section name=serverHeader overrideModeDefault=Allow />



From that point the native configuration system can handle your config section and tools like appcmd.exe know about it, e.g. you can show the standard settings of your section (according to the schema definition) with:

appcmd list config /section:serverHeader /config:*

To set configuration for an application use:

appcmd set config “Default Web Site/App” -section:serverHeader /enabled:true /value:SomeServer

You can now also use the APIs in Microsoft.Web.Administration to read/write the configuration section programmatically (I wrote more about the options here). To get a strongly typed wrapper for the configuration section you have to add a mapper class that derives from ConfigurationSection. The class is very simple and looks like this:

public class ServerHeaderConfigurationSection : ConfigurationSection


    public static readonly string SectionName = “system.webServer/serverHeader”;


    public bool Enabled


        get { return (bool)base[“enabled”]; }

        set { base[“enabled”] = value; }



    public string Value


        get { return (string)base[“value”]; }

        set { base[“value”] = value; }



Now we can add configuration functionality to the HttpModule. First of all I added a property that retrieves the current configuration. I used the WebConfigurationManager class found in Microsoft.Web.Administration. This is the light-weight read-only API that always gives you an aggregated view of all configuration settings in effect (regardless of at which level they were configured). This API also works in partial trust scenarios.

private ServerHeaderConfigurationSection _configuration = null;


protected ServerHeaderConfigurationSection Configuration




        if (_configuration == null)


            _configuration =







        return _configuration;



The OnLeave event handler can now read from config and act accordingly:

void OnLeave(object sender, EventArgs e)


    if (!Configuration.Enabled)



    // set header

    HttpContext.Current.Response.Headers.Set(“Server”, Configuration.Value);


OK – that’s it for now. We have completed two important steps – added a general request processing module to IIS and made this module available to the configuration system. In the next post I will show you how to integrate the module configuration into the IIS server side management system.


This entry was posted in Uncategorized. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s