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:

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:

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.

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

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

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.

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 and the virtual path needs to include the friendly name of the site like,
<location path="Default Web Site/EnglishPages/OneJapanesePage.aspx"&gt,
which is also shown in the example below. If the config file is a web.config file,
you can apply settings to a specific file, child directory, virtual directory, or application.

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

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 Retrieving Configuration 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 Business Objects and Debugging sections 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 Localization section of this tutorial.

<healthMonitoring>

Responsible for controlling how the server monitors the application for exceptional events, an d
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.
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.

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

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.

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

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 - The following attributes are applicable only for ASP.NET applications. The configuration system ignores these attributes when other types of applications are running.

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 or the application configuration file.

MachineToWebRoot

Allows the section to be used in the machine configuration file or the configuration file of the application
at the root of a web site (but not to other applications under that site).

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.