ASP.NET Web Configuration Guidelines

Article
02/13/2013

ASP.NET enables you to specify configuration settings that affect all Web applications on a server, that affect only a single application, that affect individual pages, or that affect individual folders in a Web application. You can make configuration settings for features such as compiler options, debugging, user authentication, error-message display, connection strings, and more.

Configuration data is stored in XML files that are named Web.config.

This topic describes the main configuration settings that you can make in the Web.config file. The topic contains the following sections:

Configuration File Sections
Modifying Configuration Files
Configuration Files Hierarchy
Deploying Configuration Files

Configuration File Sections

Configuration files are grouped into sections that contain the settings for individual features.

Compilation

In order for an application to service Web requests, ASP.NET must first compile the application into one or more assemblies.

You use the compilation configuration section to configure the settings that ASP.NET requires in order to compile Web applications. The following are some of the attributes that you can specify:

debug. During the development stage, you can set the debug attribute to true to generate the symbols that are required during debugging. At the end of the development cycle, you set the debug attribute to false in order to optimize performance
targetFramework. This attribute specifies the version of the .NET Framework that the Web site targets. This attribute should be included only for Web sites that target the .NET Framework 4 and later versions. It is used by Visual Studio to make sure that your project uses only features that are available in the targeted framework version. For more information, see .NET Framework Multi-Targeting for ASP.NET Web Projects.

The following example shows how to specify configuration settings in the compilation section. The configuration settings specify that debugging symbols should be generated, that changed files must be recompiled, and that the target version is .NET Framework 4.

<compilation debug="true" 
    optimizeCompilations="true" 
    targetFramework="4.0" />

For more information, see compilation Element (ASP.NET Settings Schema). For information about compilation, see ASP.NET Compilation Overview.

Custom Errors

You can configure how information is displayed by ASP.NET when unhandled errors occur during the execution of a Web request. You might to do this to provide additional information to the user, or to customize the standard message that is displayed by ASP.NET. The following are some of the attributes that you can specify:

mode. Specifies whether custom errors are enabled or disabled, or that verbose error messages are disabled if the error is being viewed on a computer other than the server itself. You can set mode to the following values:
- On. Specifies that custom errors are enabled. If no defaultRedirect attribute is specified, users see a generic error. The custom errors are shown to the remote clients and to the local host.
- Off. Specifies that custom errors are disabled. Detailed ASP.NET errors are shown to the remote clients and to the local host.
- RemoteOnly. Specifies that custom errors are shown only to the remote clients, and that detailed ASP.NET errors are shown to the local host. This is the default value.
defaulRedirect. Specifies the default URL to direct a browser to if an error occurs. When this attribute is not specified, a generic error is displayed instead.
redirectMode. Specifies values for how the URL of the original request is handled when a custom error page is displayed.

The following example shows how to configure error handling. The settings specify that custom errors are displayed only on remote client computers. The GenericErrorPage.htm page is displayed when an unspecified error occurs. The pages NoAccess.htm and FileNotFound.htm are displayed if HTTP 403 (Forbidden) or HTTP 404 (Not Found) errors occur when users request resources that are managed by ASP.NET.

<customErrors mode="RemoteOnly"     
    defaultRedirect="GenericErrorPage.htm">
  <error statusCode="403" redirect="NoAccess.htm" />
  <error statusCode="404" redirect="FileNotFound.htm" />
</customErrors>

For more information, see customErrors Element (ASP.NET Settings Schema).

Authentication and Roles

ASP.NET can authenticate the credentials, such as name and password, of a Web site user. By using mode attribute in the authentication configuration section, you can specify the authentication scheme for your application. The default is Windows authentication, where the Windows user's account information is used for authentication. This can be a valid choice for intranet users. In case of Internet users, you must use a different scheme, such as ASP.NET forms authentication.

The following example specifies that Web site users are authenticated by using the Windows authentication scheme:

<authentication mode="Windows"/>

The authentication configuration section provides a variety of ways to configure authorization rules for users based on roles.

For more information, see the following topics:

IIS 7 and ASP.NET Ajax

The system.webServer configuration section defines the settings for IIS 7.0 that are applied to a Web application. This section is required for running ASP.NET Ajax under Internet Information Services (IIS) 7. It is not required for earlier versions of IIS.

For more information, see How to: Configure the <system.webServer> Section for IIS 7.0.

Connection Strings

The connectionStrings configuration section specifies a collection of database connection strings. The following example shows how to specify a connection string. The settings specify the connection string name, the server that hosts the database, the name of the database, and the user credentials to access the database.

<connectionStrings>
  <add name="Sales" 
       connectionString=
         "server=myserver;database=Products;
         uid=<user name>;pwd=<secure password>" />
</connectionStrings>

For more information, see connectionStrings Element (ASP.NET Settings Schema). For more information about accessing data sources, see ASP.NET Data Access Overview.

Modifying Configuration Files

When you use Visual Studio 2010 to create a new Web site project or Web application project, a Web.config file is included in the new project. You can create or modify configuration settings in the following ways:

By using a text editor or an XML editor to change the configuration files. For information about syntax, see the configuration reference topics in ASP.NET Configuration Settings and General Configuration Settings (ASP.NET).
In IIS 6 by using the ASP.NET MMC snap-in. You can start the MMC snap-in from the Web site properties dialog box.
In IIS 7 by using the IIS Configuration Editor. You can start the editor from IIS Manager under Server Component. For more information, see IIS Configuration Editor on the TechNet Web site and Editing Collections with the IIS Configuration Editor on the IIS.net Web site.
By using the Web Site Administration Tool in Visual Studio. For more information, see ASP.NET Web Site Administration Tool.

For more information about modifying configuration settings, see Editing ASP.NET Configuration Files.

You can also create and modify the configuration settings programmatically by using the ASP.NET configuration API. For more information, see ASP.NET Configuration API.

Configuration Files Hierarchy

All .NET Framework applications inherit basic configuration settings and defaults from the Machine.config file that is used for server-wide configuration settings. These settings apply to all .NET Framework applications (including ASP.NET applications) that run on that server.

The root of the ASP.NET configuration hierarchy is the Web.config file that is located in the same directory as the Machine.config file. The root Web.config file inherits all the settings in the Machine.config file. It 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 you want to override. You can create the following Web configuration files:

A Web.config file for a specific ASP.NET application. This file is in the root directory of the application and contains settings that apply to that Web application. Settings in this file are inherited by any subdirectories in the application.
The Web.config file for an application subdirectory. This file contains settings that apply to that subdirectory and its children (if any).

This hierarchy structure enables you to set configuration details for your applications at the appropriate directory levels without affecting configuration settings at higher level. For more information, see ASP.NET Configuration File Hierarchy and Inheritance.

Deploying Configuration Files

When you deploy a Web site, often you want some settings in the deployed application's Web.config to be different than those in the development Web.config file. For example, on a production server, you might want to disable debug options and change connection strings so that they point to different databases. For Web application projects, you can create a Web.config transform file that is applied automatically during deployment in order to change the deployed versions of Web.config files.

For information about the difference between Web application projects and Web site projects, see Web Application Projects versus Web Site Projects.

ASP.NET Web Configuration Guidelines

Configuration File Sections

Compilation

Custom Errors

Authentication and Roles

IIS 7 and ASP.NET Ajax

Connection Strings

Modifying Configuration Files

Configuration Files Hierarchy

Deploying Configuration Files

See Also

Tasks

Reference

Concepts

Other Resources

Additional resources