The ASP.NET configuration system is simple to work with but offers complex functionality. Two types of configuration files are used in ASP.NET:
machine.configUsed to configure settings that are global to all .NET applications across the computer. This file can be found in C:\Windows\Microsoft.NET\Framework\[version]\CONFIG\, where [version] is replaced by the exact version number of the .NET Framework. Settings made in this file set the default behavior for all ASP.NET applications.
web.configUsed to override defaults, change inherited configuration settings, or add new configuration settings. Whereas only one copy of the machine.config file exists for each installed version of the .NET Framework, many different web.config files can exist for the Web applications you run. Each Web application can have its own web.config file, and each subdirectory within the Web application can also have its own web.config. The next section explains how all this works.
Important | You might find that you have more than one machine.config on your computer. The .NET Framework is designed to allow multiple versions to run side by side. Each version has its own separate machine.config file. The version of the .NET Framework your Web application is using is determined by the extension mappings, for example, .ASPX, in Internet Information Services. Be sure you edit the correct machine.config file if you want to change global settings. |
Figure 7-1 demonstrates a system that has two installations of the .NET Framework, version 1.0 and 1.1. Each separate version has its own subdirectory within the C:\Windows\Microsoft.NET\Framework directory.
Figure 7-1: A server with multiple installed .NET Framework installations
Two subdirectories are of interest in the C:\Windows\Microsoft.NET \Framework directory: v1.0.3705, which contains all the files for the 1.0 version of the .NET Framework; and v1.1.4322, which contains all the files for the 1.1 version of the .NET Framework.
To view the version of ASP.NET your application is running, open Microsoft Internet Information Services (IIS) Manager, right-click the Default Web Site option, and select Properties. Next, click on the Home Directory tab, and click the Configuration button. A listing of the extension mappings used by ASP.NET appears. Figure 7-2 shows the extension mapping for .ASPX, which maps to aspnet_isapi.dll in the .NET Framework version 1.1 directory. Changes made to the machine.config file in the v1.1.4322\CONFIG\ subdirectory are applied to this application.
Figure 7-2: The ASP.NET application mapping for IIS
Tip | You can change mappings to allow your application to use a different version of the .NET Framework by using the aspnet_regiis.exe tool. This tool is found in the version-specific .NET Framework directory. |
It’s uncommon to need to change machine.config settings. In fact, the only setting for ASP.NET that must be configured in machine.config is the <processModel /> section. Settings in <processModel /> are used to control the behavior of the ASP.NET worker process.
The ASP.NET worker process is relevant only to Microsoft Windows 2000 Server and Microsoft Windows XP Professional. Microsoft Windows Server 2003 uses the new Microsoft Internet Information Services 6 worker process model.
Important | Don’t modify the machine.config file unless you absolutely have to, such as changing settings to purposely affect all applications. Changes to machine.config affect the entire server. Instead, use web.config in your application to specify desired behavior and configuration options. The web.config file is the recommended location for specifying all your configuration settings. |
The web.config file is used to override configurations inherited from machine.config or other parent web.config files. The web.config file is also used to add new settings not already defined, such as custom configuration settings. This file can reside in one of two locations:
Web application or Web site root directoryThe web.config file can be placed at the root of your Web site or Web application. A Web application is determined through IIS. By default, all virtual directories are Web applications. Further, any directory in your Web site can be made into a Web application by right-clicking on the directory within the IIS MMC, selecting Properties, and clicking the Create button on the Directory tab.
Subdirectory within your Web site or Web applicationAny directory or folder within your Web site or Web application might contain a web.config file. However, some settings are allowed only in a web.config file that resides in the Web application or Web site root directory.
Note | An easy way to tell whether you are working with the root directory for either a Web site or Web application is to look for a bin subdirectory. The bin subdirectory is allowed only in the root directory of a Web site or Web application. |
Knowing the location of your web.config file is important. Some configuration settings, such as <authentication />, are allowed only at the root directory level, whereas other settings, such as <authorization />, are allowed within any directory.
Figure 7-3 shows the IIS MMC snap-in browsing a default Web site. A web.config file could be placed within any of the folders shown in the figure. However, only Default Web Site and ForumsV2 would be considered applications.
Figure 7-3: Internet Information Services MMC snap-in browsing a default Web site
The actual configuration applied to your application is a merged view of all inherited configuration settings. In the default Web site shown in Figure 7-3, settings made in machine.config are inherited by the Default Web Site and merged with its web.config. Further, those configuration settings are merged with the web.config settings in the ForumsV2 directory. Later in the chapter we’ll discuss how to control which settings can be overridden.
Table 7-1 lists the various ASP.NET configuration sections that are allowed in a Web site and Web application or subdirectory. Note that all these settings are allowed in the machine.config file.
Section | Web Site or Application | Subdirectory | Purpose |
---|---|---|---|
<authentication /> | Yes | No | Determines how HTTP requests are authenticated |
<authorization /> | Yes | Yes | Allows or denies access based on user identity or role membership |
<browserCaps /> | Yes | Yes | Enumerates browser capabilities |
<clientTarget /> | Yes | Yes | Defines alias for a rendering agent |
<compilation /> | Yes | Yes | Controls how pages and other related ASP.NET resources are dynamically compiled |
<customErrors /> | Yes | Yes | Overrides default ASP.NET error pages |
<deviceFilters /> | Yes | Yes | Filter used for specific devices to control rendering of mobile content |
<globalization /> | Yes | Yes | Controls encoding and related globalization settings |
<httpHandlers /> | Yes | Yes | Maps HTTP requests to the appropriate classes |
<httpModules /> | Yes | Yes | Configures modules that participate in an HTTP request/ response |
<httpRuntime /> | Yes | Yes | Controls max request length, number of threads, and other settings related to the ASP.NET HTTP Runtime |
<identity /> | Yes | Yes | Windows identity to use when processing HTTP requests |
<machineKey /> | Yes | No | Keys used for encryption and hashing |
<mobileControls /> | Yes | Yes | Lists settings specific to mobile controls |
<pages /> | Yes | Yes | Configure page-specific settings for the application |
<processModel /> | No | No | Configures the ASP.NET worker process, present only in machine.config |
<securityPolicy /> | Yes | No | Defines security policy for the application |
<sessionState /> | Yes | No | Session state options such as in-process and out-of-process |
<trace /> | Yes | Yes | Enables tracing at the application or page level |
<trust /> | Yes | No | Defines trust levels regarding what the application can or can not do |
<webControls /> | Yes | Yes | Identifies the location of the client script JavaScript files |
<webServices /> | Yes | Yes | Controls behavior of ASP.NET XML Web services |
Whenever an application-level configuration file or machine.config is modified and saved, several important things happen:
Settings are applied immediately.
All existing requests are completed against the old configuration settings. A new instance of the application is started, and new requests are directed to the new application.
When running a live application, you will notice a 2 to 10 second delay between the time you save or update your CONFIG file and the time the settings are actually applied to your application. When the application is restarted, all pages are recompiled and the application reinitializes itself, which takes a few seconds.
Tip | When updating a live site, perform all web.config changes locally and upload the new configuration file to the running site. This approach is much more efficient than changing and saving multiple times on the live web.config file. |
This update process is slightly different when changes are made to the <processModel /> section when running Windows 2000 Server and Windows XP Professional—you will need to stop the Web server and restart it for the changes to take effect.
The machine.config and web.config files are identical in structure, which is shown in the following code:
<configuration>
<!-- XML comments are allowed -->
<configSections>
<section name="[name]" type="[type]"
allowLocation="[true/false]"
<sectionGroup name="[name]" />
</configSections>
<[Section Group Name]>
<[Section Name] [Settings] />
</[Section Group Name]>
</configuration>
All .CONFIG files require the root XML element <configuration />. Following <configuration /> is the <configSections /> element. Configuration sections, such as <sessionState />, as shown in the following code, are used to process configuration data (which is found in machine.config).
<section name="sessionState"
type="System.Web.SessionState.SessionStateSectionHandler,
System.Web, Version=1.0.5000.0, Culture=neutral,
PublicKeyToken=b03f5f7f11d50a3a"
allowDefinition="MachineToApplication" />
Additionally, within <configSections />, <sectionGroup name=“[name]” /> is defined. The <sectionGroup name=“[name]” /> section allows for groups of common settings so that you can better organize the configuration file. For example, ASP.NET settings such as sessionState are grouped in the system.web group. Unless you are creating custom configuration sections, you will not use the <sectionGroup /> element or any of its child elements.
The next configuration section contains the actual settings. The opening element is the section group that the settings belong to, for example, <system.web>. Within this element are the actual settings, such as <sessionState />. Figure 7-4 illustrates the configuration mappings when using section groups and system.web settings.
Figure 7-4: Mapping of sections and groups