Managing Your ASP.NET Application[1]->Configuration File Format

ASP.NET configuration files are XML text files — each named web.config — that can appear in any directory of an ASP.NET Web application.
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. A root configuration file — %windir%\Microsoft.NET\Framework\version\config\machine.config — provides default configuration settings for all web applications on the entire machine that run a specific version of ASP.NET. ASP.NET configures IIS to prevent direct browser access to web.config files to ensure that their values cannot become public, and attempts to access them will cause ASP.NET to return an "403: Access Forbidden" error.
At run time ASP.NET uses these web.config configuration files to hierarchically compute a unique collection of settings for each incoming URL 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:
 

1. Base configuration settings for machine.
C:\WinNT\Microsoft.NET\Framework\v2.0.xxxxx\config\machine.config
2. Root web configuration settings for machine.
C:\WinNT\Microsoft.NET\Framework\v2.0.xxxxx\config\web.config
3. Overridden by the configuration settings for the site (or the root application).
C:\inetpub\wwwroot\web.config
4. Overridden by application configuration settings.
D:\MyApplication\web.config
5. 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. 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 Sections and Section Groups

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>

ASP.NET configuration settings are represented within configuration tag sections, also nested within a <configuration> tag (and, optionally, within section group tags). For example, in the sample below, the tag <pages> is the configuration section that defines configuration settings for the ASP.NET page compiler. Note: tag names in a configuration file 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 section groups allow hierarchical grouping of sections for organizational purposes. For example, all built-in ASP.NET sections belong in the <system.web> section group. Section groups may appear inside other section groups.
In the following example, the configuration file contains configuration settings for the built-in <pages> ASP.NET section. This section is contained within the built in section group called <system.web>.

<configuration>
<system.web>
<pages enableSessionState="true" />
</system.web>
</configuration>

Adding a Configuration Section

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 inherit from the ConfigurationSection class. An individual ConfigurationSection 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. Each section tag identifies a tag name denoting a specific section of configuration data and an associated ConfigurationSection-based class that processes it.
In the following example, the configuration file declares a new section, called <mySection>.

<configuration>
<configSections>
<section name="mySection" type="SettingsClasses.MySectionSettings" />
</configSections>
<mySection .../>
</configuration>

Collection Settings

Many of the configuration sections built into ASP.NET include settings that are collections of elements. Examples of collection settings include HTTP handler and module mappings, and providers for application services. Like all other settings, collection settings are hierarchically computed - an application's web.config, for example, can add to or remove from a collection of settings applied at the machine level.
Most collection settings have a common syntax for adding and removing elements. The <add> tag adds a new element to the collection. This tag usually includes attributes to define the element. The <remove> tag removes an existing element from the collection, and usually includes attributes that uniquely identify the element to remove. The <clear> tag clears the entire collection, removing any elements that were hierarchically inherited by the current level.
In the following example, the configuration file adds a new HTTP handler mapping for the ".webservice" file type, and removes the existing handler for the ".asmx" file type.

<configuration>
<system.web>
<httpHandlers>
<add path="*.webservice" verb="GET, POST"
type="MyHandlers.WebServiceHandler" />
<remove path="*.asmx" verb="GET, POST" />
</httpHandlers>
</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 or the root web.config file, you can apply settings to specific virtual directories or applications and the virtual path needs to include the friendly name of the site like, <location path="Default Web Site/EnglishPages/OneJapanesePage.aspx">, which is also shown in the example below. If the config file is a web.config file at a lower level, 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="Default Web Site/EnglishPages/OneJapanesePage.aspx">
<system.web>
<globalization
requestEncoding="Shift-JIS"
responseEncoding="Shift-JIS"
/>
</system.web>
</location>
</configuration>

Locking Down Configuration Settings

In addition to using the <location> tag to override configuration settings for individual paths, you can also use this tag to lock down settings at a higher level, 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 configuration disables and locks down session state for two different applications.
 

<configuration>
<location path="app1" allowOverride="false">
<system.web>
<sessionState enabled="false" />
</system.web>
</location>
<location path="app2" allowOverride="false">
<system.web>
<sessionState enabled="false" />
</system.web>
</location>
</configuration>

If a user overrides these settings in another configuration file that is lower in the application configuration hierarchy, the configuration system will throw an error at runtime when the application is run.
The ASP.NET 2.0 configuration system now also includes a number of features to lock individual elements and attributes of configuration, using the lockItems and lockCollections attributes. For more information, consult your product documentation.

Standard ASP.NET Configuration Sections

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 an alphabetic list of the built-in sections, with brief descriptions and pointers to more information.

Section Name	Description
<anonymousIdentification>	Responsible for controlling how anonymous users are tracked in the system. For more information, see the Storing User Profiles section of this tutorial.
<authentication>	Responsible for controlling the authentication settings on the applications. Applications can be configured to use Windows or Forms authentication. For more information, see the Securing Your Application section of this tutorial.
<authorization>	Responsible for controlling access to individual URLs based on the authenticated user's privileges. Typically, this setting is set at the individual file level using <location> tags. For more information, see the Securing Your Application section of this tutorial.
<browserCaps>	Responsible for controlling the settings of the browser capabilities component. For more information, see the Extending ASP.NET section of this tutorial.
<caching>	Section group responsible for controlling how the ASP.NET cache operates. For more information, see the Caching for Performance section of this tutorial.
<compilation>	Responsible for all compilation settings used by ASP.NET. For more information, see the Building a Web Application section of this tutorial.
<customErrors>	Responsible for customizing error pages returned by the application to the browser.
<globalization>	Responsible for configuring the globalization settings of an application. For more information, see the Internationalizing Your Application section of this tutorial.
<healthMonitoring>	Responsible for controlling how the server monitors the application for exceptional events, and how it handles them. For more information, see the Monitoring Your Applications section of this tutorial.
<hostingEnvironment>	Responsible for configuring the server environment that hosts ASP.NET applications.
<httpCookies>	Responsible for controlling how ASP.NET writes cookies for built-in features such as forms authentication and session state.
<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. 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.
<httpRuntime>	Responsible for configuring the ASP.NET HTTP runtime.
<identity>	Responsible for configuring the Windows user identity used to run an application, and for controlling user impersonation.
<machineKey>	Responsible for configuring the encryption key used to encrypt secrets such as forms authentication tickets.
<membership>	Responsible for configuring settings and providers for the ASP.NET membership system. For more information on membership, see the Using the Membership and Role Manager APIs section of this tutorial.
<mobileControls>	Responsible for configuring mobile controls settings, such as adapter mappings for different mobile devices.
<pages>	Responsible for configuring settings for ASP.NET pages, including defaults for settings that can be set from the <%@ Page > directive of a page, such as compilation language, session state usage, and theme.
<processModel>	Responsible for configuring the ASP.NET process model settings on IIS Web server systems.
<profile>	Responsible for configuring settings and providers for the ASP.NET user profile system. For more information, see the Storing User Profiles section of this tutorial.
<roles>	Responsible for configuring settings and providers for the ASP.NET role manager. For more information on the ASP.NET role manager, see the Using the Membership and Role Manager APIs section of this tutorial.
<sessionPageState>	Responsible for configuring how session state can be used to save page viewstate, for small devices that have limited page size or bandwidth requirements.
<sessionState>	Responsible for configuring the session state HTTP module. For more information, see the Managing State section of this tutorial.
<siteMap>	Responsible for configuring settings and providers for the ASP.NET site navigation system. For more information, see the Creating a Site Navigation Hierarchy section of this tutorial.
<trace>	Responsible for configuring the ASP.NET trace service. For more information, see the Tracing section of this tutorial.
<trust>	Responsible for configuring the trust level used to run an ASP.NET application. Applications running under limited-trust environments such as hosted servers can be configured to run under a reduced trust level, with fewer capabilities than a fully trusted application.
<urlMappings>	Responsible for configuring URL mappings used by the ASP.NET site navigation system. For more information, see the Creating a Site Navigation Hierarchy section of this tutorial.
<webParts>	Responsible for controlling settings used by ASP.NET web parts. For more information, see the Personalization Using Web Parts section of this tutorial.
<webServices>	Responsible for configuring ASP.NET web services. For more information, see the ASP.NET Web Services Quickstart tutorial.
<xhtml11Conformance>	Responsible for controlling XHTML conformance settings of ASP.NET controls. You can use these settings to control whether an ASP.NET application renders XHTML conformant output, or remains backward compatible with markup generated by earlier versions of ASP.NET.

Optional Attributes for Section Definitions - The following attributes can be optionally specified in the <section> element defining a configuration section, to control how the section can be configured. These attributes are applicable only to ASP.NET applications, and are ignored by the configuration system when running other types of applications.

Attribute	Description
allowDefinition	Specifies which configuration file the section can be used in. Use one of the following values: Everywhere Allows the section to be used in any configuration file. This is the default. MachineOnly Allows the section to be used only in the machine configuration file (Machine.config). MachineToApplication Allows the section to be used in the machine configuration file, the root web.config file, or the web.config file of any virtual directory defined to be an application. MachineToWebRoot Allows the section to be used in the machine configuration file or the root web.config file.
allowLocation	Determines whether the section can be used within the <location> element. Use one of the following values: true Allows the section to be used within the <location> element. This is the default. false Does not allow the section to be used within the <location> element.