3.1 web.config


If you have configured a Web application with IIS before, many of the configuration settings available in web.config will be familiar to you. To begin with, let's see how to use the web.config file to configure something simple, such as changing the session state timeout for an application. At the top of your virtual root directory, you would create a new text file named web.config , the contents of which specify a new value for the timeout attribute of the sessionState element, as shown in Listing 3-1.

Listing 3-1 Sample web.config File Changing the Session State Timeout
 <configuration>   <system.web>     <sessionState mode='Inproc' timeout='10' />   </system.web> </configuration> 

Note that the format of this file is standard XML, with a single top-level element named configuration . Most of the settings applied to ASP.NET applications are elements within the <system.web> element, so that is the next element specified. The sessionState element has a number of attributes, and even though in this case, we care about only the timeout attribute, we also have to specify the mode attribute because it is required for this element. Once this file is placed at the root of our virtual directory, any subsequent requests will pick up the settings we have specified, which in our case means that the session state timeout would be set to 10 minutes, instead of the default 20 minutes. A complete list of all the top-level elements that apply to ASP.NET applications and their purpose is shown in Table 3-1.

Table 3-1. Top-Level Configuration Elements Available in web.config

Element

Purpose

<authentication>

Specify the client authentication mode to use

<authorization>

Allow or deny users or roles access

<browserCaps>

Specify browser capabilities based on user agent

<clientTarget>

Define client targets

<compilation>

Control page compilation and assembly references

<customErrors>

Control error page display and define custom error pages

<globalization>

Set the request and response encoding

<httpHandlers>

Add or remove HTTP handlers

<httpModules>

Add or remove HTTP modules

<httpRuntime>

Control aspects of HTTP request processing

<identity>

Specify impersonation for this application

<machineKey>

Control the validation and decryption key

<pages>

Set defaults for page attributes globally

<processModel>

Control the behavior of the worker process

<securityPolicy>

Define trust levels with associated policy files

<sessionState>

Control session state

<trace>

Enable application-wide tracing

<trust>

Select which trust level to use

<webServices>

Specify Web service protocols and extensions

<appSettings>

Add application-specific data elements

3.1.1 Configuration Hierarchy

While it is most common to deploy a web.config file at the root of your virtual root directory for an ASP.NET application, there are several additional places where web.config files can be placed. ASP.NET supports the hierarchical application of configuration settings in a top-down fashion. Configuration files can be placed in four locations: machine, site, application, and subdirectory.

At the top of the hierarchy is a single, machine-wide configuration file called machine.config , which contains the default settings for all ASP.NET applications on that machine. This file can be found in your $FRAMEWORK\CONFIG directory, where $FRAMEWORK is the path to the .NET installation (typically something like c:\winnt\Microsoft.NET\Framework\v1.0.3705 ). The machine.config file is the only required configuration file; all web.config files are optional and are necessary only if you want to change some of the default settings defined in machine.config for your application.

The next configuration file to be consulted is the web.config file placed in the root directory of the Web site. Any configuration settings in this file are applied to all ASP.NET applications running on that site.

After that, the web.config file at the root of the virtual directory of an ASP.NET application is consulted, and any configuration settings are applied to all pages and directories within that application.

Finally, you can also place web.config files within subdirectories under the virtual root. Any configuration settings in a subdirectory configuration file apply to all pages within that subdirectory or any subdirectories below it. It is important to note that the subdirectory structure used to apply configuration settings is the one specified in the URL path, not the physical directory path on disk (although typically they mirror each other).

Figure 3-1 shows the hierarchy of configuration files for an ASP.NET application. This example demonstrates all the configuration files that would affect the ASP.NET application living under the myvdir virtual directory, which is defined within the default site on the machine. Note that when a request maps into a subdirectory of the application, additional web.config files may be applied to the processing for that request.

Figure 3-1. Hierarchy of Configuration Files

graphics/03fig01.gif

One of the advantages of this hierarchical composition of configuration settings is the level of granularity it allows. You can, for example, localize the configuration settings for a collection of pages within your application that reside in a particular subdirectory, without having to alter the top-level configuration file for that application. If you ever decide to move that subdirectory of pages to another application, their configuration settings will follow them. The disadvantage of this model is that you can never be sure exactly what configuration settings are being applied to a particular page in your application without inspecting all configuration files that apply. As you begin to work with ASP.NET configuration files, keep this in mind, and be sure to check all four configuration file locations if you see any unexpected behavior.

For example, consider the application of the three configuration files shown in Figure 3-2. The top-level machine.config file contains an httpHandlers element that maps requests for files ending in .ashx to a class called SimpleHandlerFactory . On a virtual directory on the machine ( c:\inetpub\ wwwroot \foo ) is another configuration file, with no additional settings, so requests made for .ashx files at this location are forwarded to the SimpleHandlerFactory class. However, in a subdirectory ( c:\inetpub\wwwroot\foo\bar ) a third configuration file explicitly removes the .ashx handler from the list of handlers. If a request for an .ashx file is made to this subdirectory, it will not be forwarded to the SimpleHandlerFactory class as it would have just a directory above. Although it may be convenient to use elements with this subtractive capability, it is often difficult to predict their behavior at a particular point on the disk without knowing all other configuration files that may affect their behavior.

Figure 3-2. Hierarchical Configuration Settings Example

graphics/03fig02.gif

3.1.2 Location Element

Depending on your application design, you may find it more convenient to specify configuration settings for subdirectories and files in a single configuration file instead of spreading multiple configuration files throughout your directory structure. Among other things, this approach makes it easier to see exactly what settings apply to what files by looking at a single configuration file. ASP.NET supports multiple configuration settings in a single file using the location element. The location element takes an attribute named path , which can be a path to a file or a directory, and acts as a mini configuration file within the primary configuration file. To see an example, we could write a single top-level web.config file using the location element to perform the equivalent of what the two configuration files shown in Figure 3-2 performed, as shown in Listing 3-2.

Listing 3-2 Using the location Element
 <configuration>   <location path="bar">     <system.web>       <httpHandlers>         <remove verb="*" path="*.ashx" />       </httpHandlers>     </system.web>   </location> </configuration> 

This technique is particularly useful when granting and revoking authorization rights to various sections of your application, as we will see in Chapter 11.

3.1.3 Element Placement

Most of the configuration elements available can be defined in any of the four configuration file locations: machine, site, application, and subdirectory. However, a subset of settings have restrictions on where they can be used. The authentication , sessionState , trust , and httpModules [7] elements can be defined only at the machine, site, or application levels, not at the subdirectory level. These elements all affect how the application behaves overall, and it would not make sense to apply them to only a subset of pages in the application. The processModel element is even more restricted and can exist only at the machine level. As we will see, this element controls the machine-wide process management for ASP.NET and thus cannot be applied anywhere but at the machine level.

[7] In the current release, httpModules are allowed in subdirectory configuration files, but they do not take effect. In a future release, they will not even be allowed.

3.1.4 Impact of Configuration Changes

Any changes made to a web.config file are detected by ASP.NET on the next request, and the application domain for that application is reloaded. Among other considerations, it is important to note that this causes any in-process session state and any application state to be lost. Because of this, changes to a configuration file should be kept to a minimum on a live server, and if in-process session state or application state is being used, be sure the configuration files are updated at a time that will not inconvenience users of the application. Any changes to the processModel element in the machine.config file are an additional special case. These changes will not be applied until the worker process is terminated and restarted, either by performing an IIS reset, by manually killing the aspnet_wp.exe process, or through the worker process bouncing itself for any number of reasons. Terminating the worker process loses session and application state not only for that application but for all ASP.NET applications running on that machine. For this reason, changes to the process model for a machine should happen extremely infrequently on a production machine.

3.1.5 IIS and web.config

In the current release of ASP.NET, IIS is always listening for requests and dispatching them to the ASP.NET worker process if they are ASP.NET requests. This important to realize because the configuration settings in the IIS metabase are applied before the request to the ASP.NET worker process is dispatched.

One important example of this is security. Security is configurable through the metabase for any Web application hosted with IIS. ASP.NET also has a number of configuration settings related to security, but the IIS settings are applied before the ASP.NET settings. For example, if you specify in the IIS metabase that users must be authenticated using Windows authentication, but in your ASP.NET application web.config file you have granted anonymous access, users will always be required to authenticate before they can access pages in your application. For this reason, it is a good practice to leave the IIS metabase settings at their defaults and to specify all application configuration through the ASP.NET web.config file. This strategy also simplifies installation because the only thing you need to set up in the IIS metabase is the virtual directory pointing to the ASP.NET application.



Essential ASP.NET With Examples in C#
Essential ASP.NET With Examples in C#
ISBN: 0201760401
EAN: 2147483647
Year: 2003
Pages: 94
Authors: Fritz Onion

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net