ASP.NET provides a convenient , extensible, XML-based mechanism for configuring ASP.NET and applications that run under it. It is a great improvement over the IIS metabase that was awkward to change, required IIS to be restarted, and was not easily replicated on additional servers. By contrast, ASP.NET automatically detects changes to the web.config file and transparently restarts the application; there is no need to restart IIS. And replicating an ASP.NET application configuration is as simple as copying the web.config file to the new server.
Configuration File Hierarchy
ASP.NET uses a hierarchy of configuration files. The machine.config file contains the settings for the server and is located in the %SystemRoot%\Microsoft.NET\Framework\%VersionNumber%\CONFIG\ folder. You can create web.config files to configure each of your applications, overriding the settings in machine.config . When you create a new ASP.NET web application project, Visual Studio .NET automatically creates a web.config file for you in the root directory of the application, which you can modify as required. Folders within the application can also have web.config files to customize the configuration of portions of the application.
Structure and Use of web.config
The basic structure of web.config has a format similar to machine.config . The idea is that you add to web.config only those entries for which you want to override settings in machine.config . At a minimum, web.config must have a <configuration> element and a child element, such as a <system.web> element. The following is a minimal web.config file:
<?xml version="1.0" encoding="utf-8" ?> <configuration> <system.web> </system.web> </configuration>
The <configuration> and <system.web> elements don't do anything special other than to provide the structure for other settings you want to add. By using child elements of these default configuration elements in web.config , you can, for example, change the ASP.NET HTTP runtime settings, store key / value pairs in the <appSettings> section of web.config , and add elements of your own to web.config . The recipes in this chapter will show you how to do all these things and more.
The web.config file is simply an XML file and can be edited with any text editor. As with most XML, the structure of the web.config file must conform to a defined schema (in this case, the schema is detailed in the Microsoft documentation). The web.config must also be a properly formed XML document. In other words, elements must be placed in the correct sections of the XML document and conform to the case style and exact spelling defined in the schema. If a web.config file deviates from the schema in any detail, ASP.NET will throw a parsing error exception.
Dealing with Parse Errors in Debug Mode
Parse errors stemming from the web.config file can be confusing when you are running the application in debug mode in Visual Studio. When a parse error occurs, you are typically presented with the message box shown in Figure 9-1, which asks if you want to disable future debugging for this application. You should click No and run the application without debugging, which will tell you exactly what is wrong with web.config . If you accidentally click Yes, you will need to re-enable debugging for your application. You can re-enable debugging by doing the following:
Select your project in Solution Explorer.
Open the property dialog box for the project, either by right-clicking on the project and selecting Properties or by selecting Properties from the project menu.
Select "Configuration Properties."
In the "Debuggers" section, set "Enable ASP.NET Debugging" to True.
Figure 9-1. Error message displayed with web.config parse errors in debug mode
This chapter does not attempt to address all of the configuration settings available in machine.config and web.config . Rather, it provides information on many commonly used features and several that are not well documented. Many other configuration parameters related to security and HTTP handlers are addressed in Chapter 8 and Chapter 17, respectively.