ASP.NET Configuration File Hierarchy and Inheritance

You can distribute ASP.NET configuration files throughout your application directories to configure ASP.NET applications in an inheritance hierarchy. This structure allows you to achieve the level of configuration detail that your applications require at the appropriate directory levels without affecting configuration settings at higher directory levels.

This topic contains the following sections:

• Configuration Structure

• Configuration Inheritance

• Scope of Configuration Settings

• Calculating Configuration Settings at Runtime

• Multiple ASP.NET Resources Configured in a Single File

• Conflicts Between Settings on Virtual and Physical Paths

• Restricting ASP.NET Inheritance

Configuration Structure

ASP.NET configuration files are called Web.config files, and they can appear in multiple directories in ASP.NET applications. The ASP.NET configuration hierarchy has the following characteristics:

• Uses configuration files that apply to the resources within the directory in which the configuration file is placed and to all of its child directories.

• Enables you to place configuration data where it will have the appropriate scope: the entire computer, all Web applications, an individual application, or a subdirectory within the application.

• Permits overriding the configuration settings that are inherited from higher levels in the configuration hierarchy. Also permits locking configuration settings to prevent them from being overridden by configuration settings at a lower level.

• Organizes logical groups of configuration settings into sections.

Configuration Inheritance

All .NET Framework applications inherit basic configuration settings and defaults from a file named systemroot\Microsoft .NET\Framework\versionNumber\CONFIG\Machine.config. The Machine.config file is used for server-wide configuration settings. Some of these settings cannot be overridden in configuration files that are lower down in the hierarchy.

The .NET client applications (console and Windows applications) use configuration files named ApplicationName.config to override inherited settings. The ASP.NET applications use configuration files named Web.config to override inherited settings.

The root of the ASP.NET configuration hierarchy is a file referred to as the root Web.config file, and it is located in the same directory as the Machine.config file. The root Web.config file inherits all of the settings in the Machine.config file. The root Web.config file includes settings that apply to all of the ASP.NET applications that run a specific version of the .NET Framework. Because each ASP.NET application inherits default configuration settings from the root Web.config file, you need to create Web.config files only for settings that override the default settings.

Inheritance in Collection Elements

Some configuration elements are collections such as the namespaces element and the customErrors element.

In collections, configuration settings are typically added to the collection via an add child element, removed by key name via a remove child element, or the entire collection can be cleared via a clear child element. An added setting in a child configuration file overrides a setting of the same key name in a parent configuration file unless duplicates are allowed.

If a request is received for a file in the SubDir1 directory that does not exist, ASP.NET begins to search the configuration hierarchy, starting at the most local Web.config file (which is located in the current directory, if it exists, or a parent directory). ASP.NET is searching for an error Element for customErrors (ASP.NET Settings Schema) element where the statusCode attribute equals "404". Once ASP.NET finds the configuration setting for the 404 error, the URL in the redirect attribute is returned as the response.

Scope of Configuration Settings

There are different scopes to configuration settings — some have a global scope, some are effective only to the scope of the application, the root Web.config file, or the Machine.config file.

The scope of a configuration section is defined in the allowDefinition attribute of the section Element for configSections (General Settings Schema) element in the Machine.config file for all sections that are included with ASP.NET. For example, the authentication Element (ASP.NET Settings Schema) element has an allowDefinition attribute of the MachineToApplication element. This means that the authentication element can be set in the Machine.config file, the root Web.config file, and a Web.config file at the application level. If it is set at the subdirectory level, an error is thrown. If there is no allowDefinition attribute defined for a section, then the default value is Everywhere.

The scope of a configuration setting is listed for each element in ASP.NET Configuration Settings and General Configuration Settings (ASP.NET), in the Element Information table next to Configurable Locations.

The following table lists the level at which each file is located in the configuration hierarchy, the file name, and a description of the important inheritance characteristics of each file.

The ProcessModel Element

One element, the processModel Element (ASP.NET Settings Schema) element, configures the processing model that is used for the server, including all of the ASP.NET applications that are on the server. Thus, processModel settings can be placed only in the Machine.config file, and they cannot be overridden by settings in any Web.config file.

Changes to the processModel element take effect only when the worker process is restarted, not immediately after the setting is changed as with other configuration elements.

Calculating Configuration Settings at Run Time

When the server receives a request for a particular Web resource, ASP.NET computes the configuration settings for that resource hierarchically, using all the configuration files located in the virtual directory path for the requested URL. The local configuration settings override settings in parent configuration files.

These settings are calculated once and then cached across subsequent requests. ASP.NET automatically watches for file changes and re-computes the cache when any of the configuration files change within that file's hierarchy. When the server receives a request for a particular URL, ASP.NET uses the hierarchy of configuration settings in the cache to find the requested resource.

The application is restarted when a configuration change is made unless the configuration section element includes a restartOnExternalChanges="false" attribute, or the configuration setting is contained in a separate file linked to the Web.config file using a configSource attribute.

Multiple ASP.NET Resources Configured in a Single File

When managing a large number of configuration settings or managing client Web sites in an ISP setting, it might be useful to store settings for many locations in one Web.config file. Using the path attribute of the location element, you can configure many specific ASP.NET resources that are stored in application subdirectories.

For information about how to use the location element, see How to: Configure Specific Directories Using Location Settings.

Conflicts Between Settings on Virtual and Physical Directories

Configuration settings for virtual directories are independent of physical directory structure, and virtual directories must be organized carefully to avoid configuration problems. For example, you could have an ASP.NET file named MyResource.aspx with the following physical directory structure.

C:
    \Subdir1
        \Subdir2
            \MyResource.aspx

In addition, you might have a configuration file that is located in Subdir1, a virtual directory named Vdir1 that is mapped to c:\Subdir1, and a virtual directory named Vdir2 that is mapped to c:\Subdir1\Subdir2. If a client accesses the resource with the physical location of c:\Subdir1\Subdir2\MyResource.aspx using the URL https://localhost/vdir1/subdir2/MyResource.aspx, the resource inherits configuration settings from Vdir1. However, if the client accesses the same resource using the URL https://localhost/vdir2/MyResource.aspx, it does not inherit settings from Vdir1. Creating virtual directories in this manner can cause unexpected results, or even an application failure. It is recommended that you do not nest virtual directories, or if you do, use only one Web.config file.

Restricting ASP.NET Inheritance

You might want to restrict inheritance of configuration settings to enhance application performance, maintain high reliability, and simplify administration. Restrictions are controlled by the allowOverride, lockAttributes, lockAllAttributesExcept, lockAllElementsExcept, lockItem and lockElements attributes. For more information about these attributes, see General Attributes Inherited by Section Elements.

Configuration Settings for Unhandled Exceptions

During the creation of the ASP.NET application, the settings contained by the Aspnet.config file are processed by the common language runtime (CLR). These settings, among others, instruct the CLR on how to process unhandled exceptions. The configuration setting in question is as follows:

<legacyUnhandledExceptionPolicy enabled="false" />

For more information, see Exceptions in Managed Threads.

See Also

Tasks

How to: Configure Specific Directories Using Location Settings

How to: Lock ASP.NET Configuration Settings

Reference

General Attributes Inherited by Section Elements