IISSCHEMA.EXE - A tool to register IIS7 configuration sections

A very cool aspect of IIS7’s end-to-end extensibility is the ability to define your own configuration sections for your custom web server modules and handlers, that reside in the standard IIS configuration files side by side with IIS configuration.  These configuration sections can then be read/written with all the standard IIS configuration APIs and tools including AppCmd.exe, InetMgr, Microsoft.Web.Administration, and so on. 

IIS7 architecture believes in dogfooding itself, and just like all of the stock IIS7 modules being built on public extensibility APIs, all of the IIS7’s built-in configuration sections are defined using the same mechanism that you would use to define your own custom section.  As such, from the configuration system’s perspective, there is really no difference between the <system.webServer>/<windowsAuthentication> section used by the IIS Windows Authentication module and your custom configuration section.

This post provides a tool to install, uninstall, and manage configuration sections in the IIS7 configuration store.  To skip the description of how the IIS7 configuration store works, and download the tool, jump ahead.

How IIS7 configuration schema extensibility works

The mechanism for creating IIS7 configuration sections is based entirely on describing the schema of your configuration section in an XML file located in the %WINDIR%\System32\Inetsrv\Config\Schema directory.  Unlike the ASP.NET’s configuration system (System.Configuration), there is no need to write any code.

By default, if you open this folder, you will notice the existing configuration schema that is installed with IIS:

1.       ASPNET_schema.xml     - the schema for ASP.NET configuration sections

2.       FX_schema.xml               - the schema for the .NET framework configurations sections

3.       IIS_schema.xml               - the schema for the IIS configuration sections

4.       rscaext.xml                      - the schema for the RSCA extension configuration sections

Now, if you wanted to add MyCoolSchema.xml to this list, here are the step by step instructions you would follow to add your custom configuration section:

1.       XCOPY the .XML file containing the schema definition of your section(s) to %WINDIR%\System32\Inetsrv\Config\Schema\.

2.       Declare the section in the configuration file where you would like to be able to read/write its settings.

For example, for the system.webserver/asp section the definition is in applicationHost.config and looks this:

<configSections>

  <sectionGroup name="system.webServer">

    <section name="asp" overrideModeDefault="Deny" />
    …

  </sectionGroup>
  …

<configSections>

If you want to be able to set configuration for your section at the server level (MACHINE/WEBROOT/APPHOST) or below, you will need to declare the section in the applicationHost.config file.  This way, your section will be accessible anywhere in the IIS configuration hierarchy starting from the global server level to web.config files at virtual directory level and below.

This 2 step process was meant to be completely automatable, allowing your script or installer to easily deploy custom configuration sections when configuring your modules and handlers.  In fact, step 1 is completely automatable because it requires a simple file copy.

Unfortunately, in Vista, support for step 2 was not easily accessible, missing from both the AppCmd.exe command line tool AND the Microsoft.Web.Administration APIs.  Hence, installing a custom configuration section typically required manully editing the applicationHost.config file to add the definition, or using an XML writer to inject the definition element.  There is also a way to do it using script or native/managed code targeting the AppHostWritableAdminManager COM object directly, but it’s fairly cumbersome and not well documented.  In Windows Server 2008 and Vista SP1, Microsoft.Web.Administration provides easier to use APIs to accomplish this that you can leverage but if you are running Vista right now, you can’t use that.

So, with that in mind, I wrote a tool that is meant to dramatically simplify deployment and management of IIS7 configuration sections.  It’s called IISSchema.exe and you can download it below.

IISSCHEMA.EXE – A tool for managing IIS7 configuration sections

The tool allows you to:

1.      Deploy an IIS7 schema file and automatically register all sections defined in it (the 1 step solution):

> IisSchema.exe /install <schemafile.xml>

2.      Uninstall an IIS7 schema file and automatically unregister all sections defined in it / remove configuration for those sections:

> IisSchema.exe /uninstall <schemafile.xml>

3.      Define a specific configuration section at any configuration level (optionally specifying various attributes of the section definition):

> IisSchema.exe /reg mySection

4.      Remove the section definition at any configuration level:

> IisSchema.exe /unreg mySection

5.      List the sections defined at any configuration level:

> IisSchema.exe /list

For more options for each of those commands, run the tool without parameters to display its usage help.

Download IISSCHEMA.EXE v1.0 (7/25/2007).

The tool requires x86 .NET Framework to be installed, and works on both x86 and amd64 OS.  You must run it from an elevated command line prompt started with “Run as Administrator”.  NOTE that this tool is provided by me personally and not Microsoft, is provided under the Microsoft Permissive License, and is supported exclusively by this blog.

Hopefully this will simplify the task of managing configuration schema and section definitions for your IIS7 projects.  If you have any questions / bug reports / requests, please post them here.

Thanks,

Mike