Microsoft ASP.NET QuickStarts Tutorial

Configuration File Format

ASP.NET configuration files are XML-based text files--each named web.config--that can appear in any directory on an ASP.NET Web application server. Each web.config file applies configuration settings to the directory it is located in and to all virtual child directories beneath it. Settings in child directories can optionally override or modify settings specified in parent directories. The root configuration file--WinNT\Microsoft.NET\Framework\<version>\config\machine.config--provides default configuration settings for the entire machine. ASP.NET configures IIS to prevent direct browser access to web.config files to ensure that their values cannot become public (attempts to access them will cause ASP.NET to return 403: Access Forbidden).

At run time ASP.NET uses these web.config configuration files to hierarchically compute a unique collection of settings for each incoming URL target request (these settings are calculated only once and then cached across subsequent requests; ASP.NET automatically watches for file changes and will invalidate the cache if any of the configuration files change).

For example, the configuration settings for the URL http://myserver/myapplication/mydir/page.aspx would be computed by applying web.config file settings in the following order:

Base configuration settings for machine.
C:\WinNT\Microsoft.NET\Framework\v.1.00\config\machine.config

Overridden by the configuration settings for the site (or the root application).
C:\inetpub\wwwroot\web.config

Overridden by application configuration settings.
D:\MyApplication\web.config

Overridden by subdirectory configuration settings.
D:\MyApplication\MyDir\web.config

If a web.config file is present at the root directory for a site, for example "Inetpub\wwwroot", its configuration settings will apply to every application in that site. Note that the presence of a web.config file within a given directory or application root is completely optional. If a web.config file is not present, all configuration settings for the directory are automatically inherited from the parent directory.

Configuration Section Handlers and Sections

A web.config file is an XML-based text file that can contain standard XML document elements, including well-formed tags, comments, text, cdata, and so on. The file may be ANSI, UTF-8, or Unicode; the system automatically detects the encoding. The root element of a web.config file is always a <configuration> tag. ASP.NET and end-user settings are then encapsulated within the tag, as follows:

<configuration>
    <!- Configuration settings would go here. -->
</configuration>

The <configuration> tag typically contains three different types of elements: 1) configuration section handler declarations, 2) configuration section groups, and 3) configuration section settings.

Configuration section handlers - The ASP.NET configuration infrastructure makes no assumptions regarding the file format or supported settings within a web.config file. Instead, it delegates the processing of web.config data to configuration section handlers, .NET Framework classes that implement the IConfigurationSectionHandler interface. An individual IConfigurationSectionHandler declaration needs to appear only once, typically in the machine.config file. The web.config files in child directories automatically inherit this declaration. Configuration section handlers are declared within a web.config file using section tag directives nested within a <configSections> tag. Section tags may be further qualified by section group tags to organize them into logical groups (see below). Each section tag identifies a tag name denoting a specific section of configuration data and an associated IConfigurationSectionHandler class that processes it.
Configuration section groups - ASP.NET configuration allows hierarchical grouping of sections for organizational purposes. A <sectionGroup> tag may appear inside a <configSections> tag or inside other <sectionGroup> tags. For example, ASP.NET section handlers all appear within the <system.web> section group.
Configuration sections - ASP.NET configuration settings are represented within configuration tag sections, also nested within a <configuration> tag (and optional section group tags). For each configuration section, an appropriate section handler must be defined in the config hierarchy. For example, in the sample below, the tag <httpModules> is the configuration section that defines the HTTP modules configuration data. The System.Configuration.HttpModulesConfigurationHandler class is responsible for interpreting the content contained within the <httpModules> tag at run time. Note that both the section handler definition and the section must have the same section group qualifier (in this case, <system.web>). Also note that tag names are case-sensitive and must be typed exactly as shown. Various attributes and settings for ASP.NET are also case-sensitive and will not be examined by the configuration runtime if the case does not match.

<configuration>

  <configSections>
    <sectionGroup name="system.web">
      <section
        name="httpModules"
        type="System.Web.Configuration.HttpModulesConfigurationHandler,System.Web"
      />
    </sectionGroup>
  </configSections>

  <system.web>
    <httpModules>
      <add
        name="CookielessSession"
        type="System.Web.SessionState.CookielessSessionModule,System.Web"
      />
      <add
        name="OutputCache"
        type="System.Web.Caching.OutputCacheModule,System.Web"
      />
      <add
        name="Session"
        type="System.Web.SessionState.SessionStateModule,System.Web"
      />
      <add
        name="WindowsAuthentication"
        type="System.Web.Security.WindowsAuthenticationModule,System.Web"
      />
      <add
        name="FormsAuthentication"
        type="System.Web.Security.FormsAuthenticationModule,System.Web"
      />
      <add
        name="PassportAuthentication"
        type="System.Web.Security.PassportAuthenticationModule,System.Web"
      />
      <add
        name="UrlAuthorization"
        type="System.Web.Security.UrlAuthorizationModule,System.Web"
      />
      <add
        name="FileAuthorization"
        type="System.Web.Security.FileAuthorizationModule,System.Web"
      />
    </httpModules>
  </system.web>

</configuration>

Using Location and Path

By default, all configuration settings defined within the top-level <configuration> tag are applied to the current directory location of the containing web.config file and to all of the child paths beneath it. You can optionally apply configuration settings to specific child paths under the current config file by using the <location> tag with an appropriately constraining path attribute. If the config file is the main machine.config file, you can apply settings to specific virtual directories or applications. If the config file is a web.config file, you can apply settings to a specific file, child directory, virtual directory, or application.

<configuration>

  <location path="EnglishPages">
    <system.web>
      <globalization
        requestEncoding="iso-8859-1"
        responseEncoding="iso-8859-1"
      />
    </system.web>
  </location>

  <location path="EnglishPages/OneJapanesePage.aspx">
    <system.web>
      <globalization
        requestEncoding="Shift-JIS"
        responseEncoding="Shift-JIS"
      />
    </system.web>
  </location>

</configuration>

Locking down configuration settings

In addition to specifying path information using the <location> tag, you can also specify security so that settings cannot be overridden by another configuration file further down the configuration hierarchy. To lock down a group of settings, you can specify an allowOverride attribute on the surrounding <location> tag and set it to false. The following code locks down impersonation settings for two different applications.

<configuration>

  <location path="app1" allowOverride="false">
    <system.web>
        <identity impersonate="false" userName="app1" password="app1pw" />
    </system.web>
  </location>

  <location path="app2" allowOverride="false">
    <system.web>
        <identity impersonate="false" userName="app2" password="app2pw" />
    </system.web>
  </location>

</configuration>

Note that if a user tries to override these settings in another configuration file, the configuration system will throw an error:

<configuration>

  <system.web>
      <identity userName="developer" password="loginpw" />
  </system.web>

</configuration>

Standard ASP.NET Configuration Section

ASP.NET ships with a number of standard configuration section handlers that are used to process configuration settings within web.config files. The following table provides brief descriptions of the sections, along with pointers to more information.

Section Name Description

<httpModules> Responsible for configuring HTTP modules within an application. HTTP modules participate in the processing of every request into an application. Common uses include security and logging.

<httpHandlers> Responsible for mapping incoming URLs to IHttpHandler classes. Subdirectories do not inherit these settings. Also responsible for mapping incoming URLs to IHttpHandlerFactory classes. Data represented in <httpHandlers> sections are hierarchically inherited by subdirectories. For more information, see the Http Handlers and Factories section of this tutorial.

<sessionState> Responsible for configuring the session state HTTP module. For more information, see the Managing Application State section of this tutorial.

<globalization> Responsible for configuring the globalization settings of an application. For more information, see the Localization section of this tutorial.

<compilation> Responsible for all compilation settings used by ASP.NET. For more information, see the Business Objects and Debugging sections of this tutorial.

<trace> Responsible for configuring the ASP.NET trace service. For more information, see the Tracing section of this tutorial.

<processModel> Responsible for configuring the ASP.NET process model settings on IIS Web server systems.

<browserCaps> Responsible for controlling the settings of the browser capabilities component. For more information, see the Retrieving Configuration section of this tutorial.