IIS 7.0 : Configuration File Syntax

Each configuration file uses special XML elements called configuration sections to specify configuration information. A configuration section is the basic unit of configuration, typically defining the behavior of a specific part or feature in the Web server.

Here is an example of a configuration file that specifies multiple configuration sections:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <system.webServer>

        <asp>
            <cache diskTemplateCacheDirectory="%SystemDrive%\inetpub\temp\
ASP Compiled Templates" />
        </asp>
        <defaultDocument enabled="true">
            <files>
                <add value="index.html" />
                <add value="default.aspx" />
            </files>
        </defaultDocument>

        <directoryBrowse enabled="false" />

    </system.webServer>
<configuration>

As you can see, this is a well-formed XML file, with a mandatory root <configuration> element that contains multiple subelements. These subelements are either configuration section elements directly, or section group elements such as <system.webServer>. Section groups do not define any settings, they simply group related section elements together. For example, all of the IIS Web server features are under the <system.webServer> section group. Sections are the elements, shown in bold, that contain specific configuration settings.

The configuration section elements each follow a specific structure defined by their schema, which controls what attributes and child elements are allowed inside the section, the type of data they can contain, and various other configuration syntax restrictions. The schema information is provided inside configuration schema files registered with the IIS 7.0 configuration system. Unlike the ASP.NET configuration system, which uses code to define the structure of its configuration, the IIS 7.0 configuration system is based entirely on declarative schema information.

In addition to section groups and configuration sections themselves, configuration files can also contain section declarations and location tags. Section declarations are necessary to declare a particular section before it can be used, and they also indicate what section group the section belongs to. Location tags enable configuration to be scoped to a specific configuration path, rather than to the entire namespace to which the current configuration file corresponds.

Direct from the Source: Working Around Limits on web.config File Size By default, the IIS 7.0 configuration system enforces a limit of 100 KB on the file size of web.config files. This is for security purposes, to avoid possible denial-of-service attacks on the server by providing very large configuration files. In most cases, this size should be sufficient for most situations, but what if your configuration file is bigger than 100 KB? This can happen for applications that use web.config files extensively to store custom configuration. To allow these larger files, you can override the maximum limit by adding a registry key. Create the following key. HKLM\Software\Microsoft\InetStp\Configuration Then create a DWORD value. MaxWebConfigFileSizeInKB Set this value to the file size in kilobytes (make sure you select Decimal when entering the value) to set this as a new machine-wide limit on web.config file size.

Section Declarations

Each section that is used in a configuration file contains a section declaration in applicationHost.config. Section declarations are generally created during the installation of the feature and do not typically need to be added manually. For example, following is an excerpt from the applicationHost.config configuration file that declares all IIS configuration sections.

    <configSections>
        <sectionGroup name="system.applicationHost">
            <section name="applicationPools" allowDefinition="AppHostOnly"
overrideModeDefault="Deny" />
            <section name="sites" allowDefinition="AppHostOnly"
overrideModeDefault="Deny" />
        </sectionGroup>
        <sectionGroup name="system.webServer">
        <section name="asp" overrideModeDefault="Deny" />
        <section name="defaultDocument" overrideModeDefault="Allow" />
        <section name="directoryBrowse" overrideModeDefault="Allow" />
        <sectionGroup name="security">
            <sectionGroup name="authentication">
                <section name="anonymousAuthentication" overrideModeDefault="Deny" />
                <section name="basicAuthentication" overrideModeDefault="Deny" />
            </sectionGroup>
            <section name="authorization" overrideModeDefault="Allow" />
        </sectionGroup>
    </sectionGroup>
</configSections>

					  

This fragment defines a number of IIS configuration sections, including the global <sites> and <applicationPools> sections read by WAS, and various sections for Web server features, including <asp> and <anonymousAuthentication>. You’ll also notice that these sections are nested within the appropriate section groups. Section declarations can specify a number of properties that control where the section is available, including allowDefinition, which determines at which level in the configuration hierarchy the section can be used, and overrideModeDefault, which determines if lower configuration levels can use the section by default. After the section is declared, it can be used in the current configuration file or anywhere lower in the configuration file hierarchy, meaning it does not need to be re-declared in configuration files below (re-declaring this section will actually result in a configuration error). In fact, all IIS configuration sections are declared in applicationHost.config and therefore are available in any Web site web.config configuration file. The allowDefinition and overrideModeDefault attributes control the actual ability to use this configuration section in the lower levels.

Section Groups

You use section group elements to group related configuration sections together. When you declare each section, it specifies which section group it belongs to by placing its <section> element within the corresponding <sectionGroup> element. This implicitly declares the section group itself. Section groups cannot define any attributes and therefore do not carry any configuration information of their own. Section groups can be nested within one another, but sections cannot. Think of section groups as a namespace qualification for sections.

When specifying the configuration section, you must place it inside the section group element according to the declaration. For example, when providing configuration for the <authorization> section, which is declared in the <system.webServer>/<security> section group, the configuration section must be nested in the corresponding section group elements as follows.

<configuration>
    <system.webServer>
        <security>
            <authorization bypassLoginPages="true" />
        </security>
    </system.webServer>

</configuration>

Table 1 lists most of the section groups you will find in the IIS 7.0 configuration system by default, what configuration they contain, and where they are declared.

Table 1. Section Groups

Section Group	Description	Declared In
system.applicationHost	Contains global protocol-neutral IIS configuration used by the Windows Process Activation Service, including <sites>, <applicationPools>, <listenerAdapters>, and more	applicationHost.config
system.webServer	Contains all configuration for the IIS Web server engine and features, including <modules>, <handlers>, <serverRuntime>, <asp>, <defaultDocument>, and dozens more; also contains several child section groups	applicationHost.config
system.webServer /security	Contains security-related Web server configuration, including <authorization>, <isapiCgiRestriction>, <requestFiltering> and more	applicationHost.config
system.webServer /security /authentication	Contains configuration for all authentication Web server features, including <anonymousAuthentication>, <windowsAuthentication>, and more	applicationHost.config
system.webServer /tracing	Contains configuration for tracing Web server features, including <traceFailedRequests> and <traceProviderDefinitions>	applicationHost.config
system.web	Contains all ASP.NET configuration	Framework machine.config

Not listed in Table 1, for the sake of brevity, are section groups declared in .NET’s machine.config. These sections control various aspects of the .NET Framework behavior, including system.net, system.xml.serialization, and others.

Sections

The configuration section is the focus of the IIS 7.0 configuration system, because it is the basic unit of configuration. Each configuration section has a specific structure defined by its schema, containing specific attributes, elements, and collections of elements necessary to express the required configuration for the corresponding IIS feature.

A configuration section may contain 0 or more of the elements (depending on the schema) shown in Table 2.

Table 2. Configuration Section Elements

Element	Description
Attributes	A named XML attribute, using a type specified in the schema. Supported types include int, string, timespan, enumerations, and others. Attributes may have associated validation rules, which restrict the allowed values. They may also have additional metadata such as default values, or they may specify whether or not the attribute must be specified when the section is used.
Child elements	Child XML elements, which in turn can contain attributes and other child elements.
Collections	A collection is a child element that can contain a list of other child elements (typically <add>, <remove>, and <clear>) that can be used to create lists of configuration items. Collection elements have metadata associated with them that define their behavior, including what attributes serve as collection item keys, the order in which collection items are added when collections are merged between configuration files, and more.

Most configuration sections specify default values for all of the attributes in their schema. This becomes the default configuration for that section if it’s not defined in any configuration file (by default, collections are always empty). Each configuration file can specify the section element to explicitly set the value of one or more attributes, or modify the collections in the section. The section can be specified at multiple configuration files, in which case when the configuration system retrieves the contents of this section for a particular configuration path, it merges the contents of all instances of this section. Merging attributes overrides the values specified in the configuration levels above, and merging collections adds/removes/clears items in collections based on the usage of collection elements.

For example, here are the contents of a web.config file that you could place in the root of a PHP application. The contents contain the configuration for the <defaultDocument> section and enable the index.php page to serve as a default document.

<configuration>
  <system.webServer>
    <defaultDocument enabled="true">
      <files>
        <add value="index.php" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

This configuration overrides the global enabled attribute set in applicationHost.config or a higher order web.config, setting its value to “true”. It also adds a new item to the <files> collection to enable “index.php” to serve as a default document. If configuration files earlier in the hierarchy defined other default document types in the <files> collection, then the effective collection for your application would contain those items plus the item we just added at our scope. Likewise, if the parent configuration files disabled the default document feature by setting its enabled attribute to “false”, our configuration will override that value for the application.

Configuration Section Schema

All IIS configuration sections are defined in the IIS_Schema.xml file located in a schema file in the %windir%\system32\inetsrv\config\schema directory. To learn more about the syntax of each configuration section, you can review its schema. For example, here is an excerpt from the schema definition for the <defaultDocument> configuration section.

  <sectionSchema name="system.webServer/defaultDocument">
    <attribute name="enabled" type="bool" defaultValue="true" />
    <element name="files">
      <collection addElement="add" clearElement="clear" removeElement="remove"
mergeAppend="false">
        <attribute name="value" type="string" isUniqueKey="true"/>
      </collection>
    </element>
  </sectionSchema>

					  

The schema contains the definitions for the “enabled” attribute and the <files> collection that we used earlier to set default document configuration. As you can see, the schema contains more information than just the structure of the configuration section—it also contains various metadata about the format and behavior of attributes and collections, including the types for attributes and which attributes serve as unique keys for collections. The <defaultDocument> section is a fairly simple section, so it doesn’t fully illustrate the flexibility of section schema information, but it is a good example of how you can use the schema information to define configuration sections and control their behavior.

Note

When working with IIS configuration, you will likely never have to work with section schema. However, it is useful to know where the schema information is located if you need a reference for the structure and semantics of IIS configuration sections. You should never attempt to modify the IIS schema files. However, if you are developing new IIS features, you can publish custom configuration schema files into the inetsrv\config\schema directory in order to use new configuration sections with the IIS configuration system.

In the schema directory, you will also find the FX_schema.xml and ASPNET_schema.xml files, which contain the schema definitions for .NET Framework and ASP.NET configuration sections respectively.

The IIS 7.0 configuration system is fully extensible. Custom configuration sections registered with the IIS 7.0 configuration schema will have their own schema files published in the schema directory.

Location Tags

By default, configuration specified in a particular configuration file applies to the entire URL namespace corresponding to that file. For example, configuration set in applicationHost.config applies to the entire server, and configuration set in the site’s root web.config file applies to the entire site (unless overridden by more specific web.config files). This works most of the time. However, in some cases it is necessary to apply configuration to a specific subset of the URL namespace, or to a specific URL. Location tags are the mechanism that enables this by specifying a configuration path for which all configuration specified within a location tag applies.

Here is an example of using a location tag to scope configuration to a specific Web site.

   <location path="Default Web Site">
       <system.webServer>
           <directoryBrowse enabled="true" />
       </system.webServer>
   </location>

This location tag, when specified in applicationHost.config, applies the <directoryBrowse> configuration section to the “MACHINE/WEBHOST/APPHOST/Default Web Site/” configuration path.

You can find Location tags in use with three common scenarios in IIS 7.0:

1. Defining site-specific directory or file configuration in applicationHost.config. This is necessary to apply specific configuration for a content in a Web site without defining it in the site’s web.config. For example, this is the technique commonly used by shared hosting servers to set site-specific configuration without giving the site administrators control over that configuration. When making changes to configuration in the IIS Manager or one of the programmatic interfaces, if a setting is not delegated, it is written to applicationHost.config by using location tags.

2. Locking or unlocking a specific configuration section for a particular configuration path. By placing a configuration section inside the location tag for a particular path, you can use the overrideMode attribute on the location tag to lock or unlock this configuration section for that path. For example, this is necessary for configuration sections declared with overrideModeDefault = Deny so that you can allow delegated configuration in web.config files.

3. Specifying configuration for a specific nonphysical URL. If you need to apply specific configuration to a URL that does not correspond to a physical directory (a file or a virtual URL), it’s necessary to define it using a location tag inside a physical parent directory.

   You can use a location tag to keep all of the configuration for a site or application in a single web.config file, instead of placing pieces of it in many different web.config files in various subdirectories.