Edit

Share via

Introduction to ApplicationHost.config

  • Article

by Tobin Titus

Introduction

ApplicationHost.config is the root file of the configuration system when you 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 %windir%\system32\inetsrv\config directory. 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 for the reader to not skip reading the description for that section in particular.

Note the following:

  1. This document specifies the content of each configuration section, as appears in applicationHost.config. By design, many of the sections are empty or not complete (only some of their content appears in the XML). The rest of the values are taken from the schema defaults. This is done to avoid too much information and cluttering of the file, and in order to keep it reasonably readable.

    • For full schema reference, including default values for all properties in every section, their valid ranges, etc., refer to %windir%\system32\inetsrv\config\schema\IIS\_Schema.xml (for IIS settings), or ASPNET\_Schema.xml (for ASP.NET settings), or FX_Schema.xml (for other .NET Framework settings).
    • For convenience, chunks of these files are included in this document in the appropriate sections so the reader can understand which properties are available, what the default values are, etc., for each section. See the additional note below about how to read schema information.

  2. Make a backup of the file before making any changes to it.

How to Read Config Schema

As noted above, 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 a 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 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 7.0 and above).

<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:

<sectionSchema name=""  <!-- [String, Required] [XML full path of the section] --> >
    <!-- sub-elements here describing rest of schema; -->
    <!-- their description is right below in the doc. --> 
</sectionSchema>

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 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).

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 them 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. In applicationHost.config:

<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 keys]
    allowUnrecognizedAttributes="false"  [bool] [Indicates if non-schema attributes ok]
/>

Enum Schema

Every attribute of type "enum" must define its enum values in 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 enum]
    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, the value should be in multiples of 2.

<flags            
    name=""  [String, Required] [Friendly name of the flag]
    value="" [int in power 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 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="trimWhiteSpaceString"
validationParameter=""

XML Header

Every configuration file is an XML file and may optionally include the following line as the first line:

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

In addition, it must include all its content within an XML <configuration> tags:

<configuration>

   <!-- [All of the context goes here] -->

</configuration>

ApplicationHost.config includes the above lines in it. The rest of this document walks through the rest of the sections in the file.

<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; section 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.