IIS 7 and IIS 8 Configuration Reference

by Tobin Titus

Introduction to ApplicationHost.config

Note

A detailed configuration reference for IIS is available at https://www.iis.net/configreference.

ApplicationHost.config is the root file of the configuration system when your are using IIS 7 and above. It includes definitions of all sites, applications, virtual directories and application pools, as well as global defaults for the web server settings (similar to machine.config and the root web.config for .NET Framework settings).

It is also special in that it is the only IIS configuration file available when the web server is installed (however, users can still add web.config files if they want to). It includes a special section (called configSections) for registering all IIS and Windows Activation System (WAS) sections (machine.config has the same concept for .NET Framework sections). It has definitions for locking-down most IIS sections to the global level, so that by default they cannot be overridden by lower-level web.config files in the hierarchy.

The location of the file is currently in the system32\inetsrv directory, but this is expected to change after beta2 to system32\inetsrv\config. This document walks through all the sections in the order they appear in the file, and explains them one by one. The most complex section is <system.webServer>,so it is recommended that the reader not skip that section in particular.

How to Read Configuration Schema

As noted earlier, this document contains snippets of schema information for each section, so the reader can discover what properties are available and what their default values and valid ranges are. The snippets are taken directly from the configuration schema file for IIS settings: %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml. This section explains how to read schema information.

The schema for each configuration section is defined in an XML element. There is no schema definition for section groups. The following format is used here to explain how to read the schema:

<attribute-name>="<default-value>" [<metadata>] [<description>]

<attribute-name> is the name of the configuration attribute, as it appears in XML. Every attribute must have a name.

<default-value> is the value used by default, if no other value is specified in the XML for the attribute. Not all attributes have default values (for example, site name). In this case, the syntax will be "".

<metadata> contains several items:

  • The runtime type of the attribute. This is one of "bool", "enum", "flags", "int", "int64", "String", "timeSpan". Every attribute must have a type.
  • "bool" is "true" or "false".
  • "enum" is a set of possible values, where only one of them can be set for the attribute. Every such value has a numerical value and a friendly name. The syntax is using the character "|" as a delimiter between the friendly names: value1|value2|…|valueN.
  • "flags" is similar to "enum", except that combinations of values are allowed. Therefore the numerical values should be in multiples of 2, so they can be ORed together to form combinations. The syntax is identical to "enum": value1|value2|…|valueN.
  • "int" is a 32 bit integer.
  • "int64" is a 64 bit integer.
  • "String" is a character string.
  • "timeSpan" is a representation of a time unit, similar to the managed-code type TimeSpan. It can be persisted as a number (representing seconds, or minutes); or as a formatted string in the form of "[dd:]hh:mm:ss". The "[dd:]" element represents an optional number of days. The other elements represent numbers of hours, minutes and seconds, respectively. The "timeSpanFormat" attribute specifies which format should be used: number of seconds, number of minutes, or a formatted string.
  • Required attributes are marked "Required". It means that a value for them must be set in the XML. For example, site name is a required attribute (every site must have a name in IIS).

<description> is a short description of the attribute.

Section Schema

The <sectionSchema> XML element is the base unit of schema information. All other schema information is specified within it. It has one attribute directly in it ("name"), and then the rest of the schema is in sub-elements within it.

Attribute Schema

Every attribute is defined in a corresponding <attribute> XML element in the schema. The <attribute> element may be in the <sectionSchema> element directly (if the attribute is in the section scope); or in the element (if the attribute is in a sub-element within the section); or in the <collection> element (if the attribute is in a collection within the section).

An attribute schema must specify a name and a runtime type for the attribute. It may mark the attribute as required. It may mark the attribute as the unique key (if inside a collection), or as part of a collection key (together with other attributes). It may specify a default value for the attribute. It may mark the attribute for automatic encryption on-disk. It may specify if the word "Infinite" is allowed as a value for the attribute (only for numeric types such as int and in64, and for timeSpan). It may specify the timespan format (seconds, minutes or formatted string) for timespan attributes. It may specify validation rules for the attributes (see Attribute Validation section below in this document).

<ATTRIBUTE			
    name=""  [String, Required] [XML name of the attribute]    type=""  [bool|enum|flags|int|int64|string|timeSpan, Required][Runtime type]
    required="false"  [bool] [Indicates if must be set]
    isUniqueKey="false"    [bool] [Serves as the collection key]
    isCombinedKey="false"  [bool] [Part of a multi-attribute key]
    defaultValue=""  [String] [Default value or comma-delimited flags]
    encrypted="false"  [bool] [Indicates if value persisted is encrypted]  
    allowInfinite="false"  [bool] [Indicates if "Infinite" can be set]
    timeSpanFormat="string" [string|seconds|minutes] [hh:mm:ss or number]
    validationType=""       [See validation below]
    validationParameter=""  [See validation below]			

/>

Element Schema

Every element is defined in a corresponding <element> XML element in the schema. Elements can be nested. An element is simply a container for other attributes, or sub-elements. It must have a name and it may serve as a container of default values for collection elements (for example, siteDefaults holds the default values for sites in the <sites> collection).

<ELEMENT>
    name=""  [String, Required] [XML name of the element]
    isCollectionDefault="false"  [bool] [Indicates if default values are held for other elements in this collection] 
/>

Collection Schema

Every collection is defined in a corresponding <collection> XML element in the schema. Collections contain multiple elements, which can be added and removed from it individually. Typically the collection directive names are "add", "remove" and "clear", but some collections use different names for clarity (for example, the collection is using "site" instead of "add"). This is done by specifying values for addElement, removeElement and clearElement in the collection schema. If a collection directive is missing from the schema, the collection will not support it. The collection schema may specify the name of a default element, that will be used as a container of default values for collection elements (this complements isCollectionDefault in the element schema).

For example, the collection is using siteDefaults as the default element. Most collections append elements as they merge configuration files down the namespace, but some may specify mergeAppend="false" in the schema to have a prepend behavior. For example, consider two levels of configuration: applicationHost.config and web.config in a site.

<myCollection>

    <add value="1"/>

</myCollection>

In web.config:

<myCollection>

    <add value="2"/>

</myCollection>

If the collection appends, its merged (effective) configuration at the site level will be:

<myCollection>

    <add value="1"/>

    <add value="2"/>

</myCollection>

However, if it prepends, it will be:

<myCollection>

    <add value="2"/>

    <add value="1"/>

</myCollection>

Some collections may allow duplicate entries by specifying allowDuplicates="true" in their schema. This is mostly done to support legacy collections in the .NET framework (in machine.config).

Some collections may allow additional attributes in them, beyond those specified in the schema. This is done by specifying allowUnrecognizedAttributes="true" in their schema. It is mostly done to support provider-based collections in the .NET framework.

<COLLECTION

    addElement=""     [String] [Name of Add directive, if supported]
    removeElement=""  [String] [Name of Remove directive, if supported]
    clearElement=""   [String] [Name of Clear directive, if supported]
    defaultElement="" [applicationDefaults|applicationPoolDefaults|siteDefaults|virtualDirectoryDefaults] [See isCollectionDefault]
    mergeAppend="true"  [bool] [Indicates whether or not deepest set values are appended]
    allowDuplicates="false"  [bool] [Indicates if multiple elements may have the same key]
    allowUnrecognizedAttributes="false"  [bool] [Indicates if non-schema attributes are ok]  

/>

Enum Schema

Every attribute of type "enum" must define its enum values a corresponding <enum> XML element in the schema. Every value must have a friendly name and a numerical value.

<ENUM

    name=""  [String, Required] [Friendly name of the enumerator] 
    value="" [int, Required] [Numeric value]

/>

Flags Schema

Every attribute of type "flags" must define its flag values in a corresponding XML element in the schema. Every flag must have a friendly name and a numerical value that can be ORed together with other values, to form combinations; therefore it should be in multiples of 2.

<flags  [Can be used together to form combinations, unlike enums] 

    name=""  [String, Required] [Friendly name of the flag]
    value="" [int in powers of 2, Required] [Numeric value]  

/>

Attribute Validation

Attribute validation is done when parsing the XML to get a section from the file, and when calling the configuration API to set values. If validation fails, it fails the desired operation (getting the section or setting the invalid value).

Each attribute may associate one validator for its value. This is done by specifying the appropriate validator name in the validationType, and additional parameters in the validationParameter, in the attribute schema.

The system supports these validators:

ApplicationPoolName validator

  • This validator fails on these characters: |<>&\ / [] +=;:,?* @ "
  • validationType="applicationPoolName"
    validationParameter=""

IntegerRange validator

  • This validator fails if value is outside [inside] range, in integers.
  • validationType="integerRange"
    validationParameter="<minimum>,<maximum>[,exclude]"

NonEmptyString validator

  • This validator fails if string value is not set.
  • validationType="nonEmptyString"
    validationParameter=""

SiteName validator

  • This validator fails on these characters: /.?
  • validationType="siteName"
    validationParameter=""

TimeSpanRange validator

  • This validator fails if value is outside [inside] range, in seconds.
  • validationType="timeSpanRange"
    validationParameter="<minimum>,<maximum>,<granularity>[,exclude]"

TrimWhiteSpace validator

  • This validator fails if white space is set at start or end of value.
  • validationType="requireTrimmedString"
    validationParameter=""

<configSections> Section

This is the very first section in the file. It contains a list of all other sections in the file. This is the point of registration for the sections (for example, to unregister a section from the system, remove its line from this section – no need to remove its schema file from the config\schema directory).

Note that other configuration files may have a section as well at the very top of the file. This may be useful to register sections at levels lower than the global level. These sections will be registered for that scope of the namespace only. Web.config files can only add sections to the system; they cannot redefine sections that were registered in parent levels, and they cannot remove (unregister) sections.

The sections are structured by their hierarchy of containing section groups. Each section registration specifies the section name; the managed-code type of the section handler (this has no meaning in this file and will get removed after beta2 – it is used only by System.Configuration, so it will still exist in machine.config and web.config files); the allowDefinition level, if differs from the default; and the overrideModeDefault (this attribute is used to lockdown most IIS sections in this file).

Note

Section is the basic unit of deployment, registration, locking, searching and containment of configuration settings. Every section belongs to one section group ("immediate parent"). Section group is a container of logically-related sections, and is used solely for purposes of structured hierarchy. No operations can be done on section groups. Section groups cannot have configuration settings directly (the settings belong to sections). Section groups may be nested; sections cannot.

Schema

<SECTION 
    name=""  [Required, Collection Key] [XML name of the section]
    allowDefinition="Everywhere" [MachineOnly|MachineToApplication|Everywhere] [Level where it can be set]
    overrideModeDefault="Allow"  [Allow|Deny] [Default delegation mode]

/>

Locking

Most IIS sections are locked down by default, using overrideModeDefault="Deny" in the section. The recommended way to unlock sections is by using tags, as follows:

<location path="Default Web Site" overrideMode="Allow"> 
    <system.webServer> 
        <asp /> 
    </system.webServer> 
</location>

The above location tag unlocks the section for the default web site only. To unlock it for all sites, specify this in applicationHost.config:

<location path="." overrideMode="Allow"> 
    <system.webServer> 
        <asp /> 
    </system.webServer> 
</location>

Note

path="." and path="" have the same effect. They refer to the current level in the hierarchy.

Summary

This hopefully familiarizes you with the new, powerful structure of the new applicationhost.config. To drill-down into the different pieces, you should review the IIS Schema located in %windir%\system32\inetsrv\config\schema\iis\_schema.xml.