Share via

ASP.NET Configuration File Hierarchy and Inheritance

  • Article

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.

Note

Some collections that existed in earlier versions of the .NET Framework use a different element name for the add child element. For example, the customErrors element uses an error child element to add custom errors to the collection.

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.

Configuration level

File name

File description

Server

Machine.config

The Machine.config file contains the ASP.NET schema for all of the Web applications on the server. This file is at the top of the configuration merge hierarchy.

Root Web

Web.config

The Web.config file for the server is stored in the same directory as the Machine.config file and contains default values for most of the system.web configuration sections. At run time, this file is merged second from the top in the configuration hierarchy.

Web site

Web.config

The Web.config file for a specific Web site contains settings that apply to the Web site and inherit downward through all of the ASP.NET applications and subdirectories of the site.

ASP.NET application root directory

Web.config

The Web.config file for a specific ASP.NET application is located in the root directory of the application and contains settings that apply to the Web application and inherit downward through all of the subdirectories in its branch.

ASP.NET application subdirectory

Web.config

The Web.config file for an application subdirectory contains settings that apply to this subdirectory and inherit downward through all of the subdirectories in its branch.

Client application directory

ApplicationName.config

The ApplicationName.config file contains settings for a Windows client application (not a Web application).

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.

Note

When ASP.NET is running under Internet Information Services (IIS) 6.0 in worker process isolation mode, the IIS 6.0 process model is used and the settings in the processModel section of the Machine.config file are ignored. To configure the process identity, cycling, or other process model values, use IIS Manager to configure the IIS worker process for your application. ASP.NET 2.0 will not run when you configure IIS 6.0 to run ASP.NET in IIS 5.0 isolation mode.

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 locationelement, 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