Configuration Files

Configuration Files

ASP.NET provides extensive support for configuring its behavior with the use of XML-based configuration files. Use of XML files to store configuration makes server-side administration easier for the following reasons:

  • XML files are plain-text files and can be modified using a simple text editor such as Notepad.

  • To apply configuration changes, all you need to do is copy these XML files to an appropriate location. The new settings automatically take effect and, in most cases, there's no need to stop and restart the ASP.NET process or reboot the computer.


If you change the <processModel> element in the machine.config file, you must restart Internet Information Services (IIS) for the changes to take effect. This element controls internal IIS settings such as which processors to use on a multiprocessor computer and the number of threads to allocate to ASP.NET.


Although changes to configuration files are picked up automatically by ASP.NET, it doesn't mean that you can change things without consequences. When you change an application's configuration file, ASP.NET clears all the application state and session state variables for that application. If you change the web.config file for a particular site, ASP.NET clears the state settings for every application on the affected site. In addition, if you change the machine.config file, you lose all the state settings for every site on the Web server.

Anatomy of a Configuration File

The easiest way to learn about the structure of configuration files is to look inside one. Let's start with the master configuration file that configures ASP.NET's operations on the computer. Its name is machine.config, and you'll find it in the Microsoft .NET installation directory. For example, on Windows Server 2003, this file is at the following location:


If you browse through the machine.config file on your computer, you'll get a sense of what you can configure in this fashion. The file includes some comments to show you the allowable options for settings. Figure lists the various sections you can specify in this (and other) configuration files.

Configuration File Sections


Used for


Allows access to a resource


Specifies the assemblies to use for dynamic compilation


Configures authentication


Configures authorization


Detects the user's browser type


Specifies user agent aliases


Specifies the compiler settings


Specifies the supported compilers


Specifies the name and password credentials for authenticating users


Specifies the custom error messages


Denies access to a resource


Configures forms-based authentication


Configures globalization settings


Maps incoming requests to HTTP handlers


Manages HTTP modules within an application


Configures the HTTP runtime


Configures the application identity


Specifies the page-specific configuration information


Controls the ASP.NET process model


Contains protocols used to decrypt client data


Maps security levels to policy files


Specifies service description format extensions


Configures session state options


Specifies SOAP extensions


Configures application tracing


Configures code access security


Defines users


Specifies the settings for Web services


For a complete list of what can appear in each element in a configuration file, see

The Configuration File Hierarchy

Configuration files are treated as a hierarchy by ASP.NET. The machine configuration file (machine.config) controls settings for the entire computer. Settings in machine.config can be overridden for a particular Web site hosted on the computer by a configuration file (web.config) located in the root folder of that Web site. Those settings themselves can be overridden for a particular Web application (virtual directory) by an application-specific configuration file (web.config). These settings, in turn, can be overridden by a configuration file (web.config) that applies to only part of an application.

For example, if you have a URL such as http://localhost/AppDir/SubDir/default.aspx, the code executing in default.aspx could be affected by the following configuration files, in this order:

  1. The machine.config file

  2. The web.config file in the root directory of the localhost Web server

  3. The web.config file present in the application's root directory AppDir

  4. The web.config file present in the subdirectory SubDir

At any time, the web.config file closest in the folder chain to the page being displayed overrides the similar settings defined in the other configuration files. Several other factors complicate this simple picture of how things work, including

  • A setting in a configuration file can be marked with a location element— For example, you might tag a particular section with the element <location path="Subdir1">. Settings contained in this element will apply only to pages stored in the Subdir1 subdirectory of the application.

  • ASP.NET configuration files apply only to ASP.NET resources— For example, any HTML page remains unaffected by the settings in the configuration files.

  • Any configuration file can mark an element with the allowOverride="false" attribute— In this case, more specific configuration files cannot override this setting.

Reading Configuration Settings from Code

The .NET Framework also provides programmatic access to the configuration files. For example, say you have defined a custom key in the <appSettings> element as follows:

  <add key="Custom" value="Custom configuration value" />

You could therefore read it in your program using the following expression:


To read one of the built-in values, you need to know which object in the ASP.NET object model consumes that setting. For example, the Mode property of the Session object exposes the value of the mode attribute of the <sessionState> element in the configuration file. The Mode property can be accessed using the following expression:


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows