INFO: ASP.NET Configuration Overview (307626)

MORE INFORMATION

Configuration involves everything from application settings such as database connections to security details and information about how errors should be handled. Configuration files provide a location for computer-specific and application-specific information that you can change without having to recompile code.

This article addresses the following configuration topics:

• Configuration: What's New
• File Format and Configuration Hierarchy
• ASP.NET Configuration Sections
• Retrieving Configuration Information
• Extending the Configuration Section

Configuration: What's New

In contrast to Active Server Pages (ASP) application settings that are stored in the Microsoft Internet Information Services (IIS) metabase, ASP.NET configuration settings are stored in Extensible Markup Language (XML) files. This provides the following advantages when you need to change configuration settings and deploy applications:

• ASP.NET configuration files are stored in the same directory as the site content. At deployment time, you only need to copy the content directory to obtain both the content and the application configuration.
• You can use standard text editors to modify configuration files. This makes it easy to change configuration settings both locally and remotely.
• The configuration files are extensible; as a result, you can add your own custom configuration settings.
• The system automatically detects changes to ASP.NET configuration files. You do not have to restart IIS or reboot the Web server for the settings to take effect.

File Format and Configuration Hierarchy

There are two types of configuration files with which you should be concerned for ASP.NET applications: Machine.config and Web.config. Both files are XML-based and contain similar configuration sections. However, the Machine.config file contains configuration information about all .NET applications for a specific version of the framework, whereas the Web.config files contain more granular configuration settings about specific ASP.NET applications. The text in Machine.config and Web.config is case-sensitive.

For more information about the format of ASP.NET configuration files, refer to the following topic in the .NET Framework Software Development Kit (SDK) documentation: When a request for an .aspx page is made, the configuration files are compiled in such a way that a configuration setting in a Web.config file that is stored in a subdirectory overrides a setting in a Web.config file in an application directory, which overrides settings on the Web site level and settings in the Machine.config file. After the configuration settings are compiled, they are cached for future requests until one of the configuration files is modified.

The following table lists sample configuration file locations for the http://myserver/myapplication/mydir/mypage.aspx URL:

Level	Path
Configuration settings for this version of the .NET Framework	Winnt\Microsoft.net\Framework\v.version\Config\Machine.config
Web site settings	Inetpub\Wwwroot\Web.config
Application settings	Inetpub\Wwwroot\Myapplication\Web.config
Subdirectory settings	Inetpub\Wwwroot\Myapplication\Mydir\Web.config

A Web.config file at any level is optional, but a Machine.config file is required.

For more information about configuration hierarchy, refer to the following topic in the .NET Framework SDK documentation: To apply configuration settings to specific resources, use a <location> tag with an appropriate path attribute. You can use the path attribute to identify a specific file or child directory to which unique configuration settings apply.

For more information about the <location> tag, refer to the following topic in the .NET Framework SDK documentation:

ASP.NET Configuration Sections

The ASP.NET configuration sections are contained in the <system.web> section, which is contained in the <configuration> tag:

   <configuration>
      <appSettings></appSettings>
      <system.web>
         ...
         <webServices></webServices>
      </system.web>
   </configuration>
				

The following table lists all of the ASP.NET configuration sections:

Section	Description
<appSettings>	Configures custom settings for an application. The settings in this section can be compared to application variables.
<authentication>	Configures the authentication mode to determine which type of authentication to use.
<authorization>	Configures authorization support and controls client access to URL resources.
<browserCaps>	Configures the settings of the browser capabilities component.
<compilation>	Configures all the compilation settings that ASP.NET uses.
<customErrors>	Provides information about custom error messages for an ASP.NET application.
<globalization>	Configures the globalization settings for the application.
<httpHandlers>	Maps incoming URL requests to the IHttpHandler classes.
<httpModules>	Adds, removes, or clears HTTP modules within an application.
<httpRuntime>	Configures ASP.NET HTTP run-time settings.
<identity>	Controls the application identity of the Web application.
<machineKey>	Configures keys to use for encryption and decryption of Forms authentication cookie data. This section allows you to configure a validation key that performs message authentication checks on view state data and forms authentication tickets.
<pages>	Identifies page-specific configuration settings.
<processModel>	Configures the ASP.NET process model settings on IIS Web server systems. Note that you can only use this tag in the Machine.config file.
<securityPolicy>	Defines valid mappings of named security levels to policy files.
<sessionState>	Configures the session state module.
<trace>	Configures the ASP.NET trace service.
<trust>	Configures the set of code access security permissions that is used to run a particular application.
<webServices>	Controls the settings of ASP.NET Web Services.

Retrieving Configuration Information

You can retrieve information that is stored in the configuration file, but the methods vary for the different configuration settings. Some settings are exposed as properties of the intrinsic objects, and other settings are inaccessible because they are internal settings to ASP.NET.

For example, you can use the following code to access the <browserCaps> settings through the Request.Browser object:

Microsoft Visual Basic .NET

Response.Write(Request.Browser.VBScript.ToString())
				

Microsoft Visual C# .NET

Response.Write(Request.Browser.VBScript.ToString());
				

For more information about how to retrieve configuration settings, refer to the following topic in the .NET Framework SDK documentation:

Extending the Configuration Section

The .NET Framework configuration functionality is fully extendable. There are two ways in which you can extend configuration:

• Create a custom configuration section handler.
  
  For additional information about how to create custom ASP.NET configuration section handlers, click the article number below to view the article in the Microsoft Knowledge Base:

  309045 HOW TO: Create a Custom ASP.NET Configuration Section Handler in Visual C# .NET

• Use the <appSettings> section to store application specific data. For information on the syntax of the <appSettings> section, refer to the following topic in the .NET Framework SDK documentation:

  http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpgenref/html/gngrfappsettingselement.asp

  To retrieve values from the <appSettings> section, use the following code in the .config file:

          <appSettings>
  		<add key="MySetting" value="Valuable Information" />
          </appSettings>
  						

  Then use the following code to retrieve the value:
  
  NOTE: You must include the System.Configuration namespace to access appSettings.
  
  Visual Basic .NET

      Label1.Text = ConfigurationSettings.AppSettings.Item("MySetting")
  					

  Visual C# .NET

      Label1.Text = ConfigurationSettings.AppSettings["MySetting"];