Configuration Overview

ASP.NET configuration can be summarized as: a simple but powerful XML-based configuration system . Rather than relying upon the IIS metabase as with the ASP applications, ASP.NET uses an XML-based configuration system. XML is used to describe the properties and behaviors for various aspects of ASP.NET applications.

The ASP.NET configuration system supports two types of configuration file:

• Server configuration :Server configuration information is stored in a machine.config file. This file represents the default settings used by all ASP.NET web applications. ASP.NET installs a single machine.config file on the server. You can find machine.config in [WinNT\Windows]\Microsoft.NET\Framework\[version]\CONFIG\ .

  Note

  A single machine.config file is installed for each version of ASP.NET installed. For example, if you have both ASP.NET 1.0 and ASP.NET 1.1 installed, you will have two separate version directories, v1.0.3705 and v1.1.4322 for version 1.0 and 1.1 respectively, of the .NET Framework. The CLR, and thus ASP.NET, supports the concept of side-by-side execution.

• Application configuration :Application configuration information is stored in a web.config file. This file represents the settings for an individual ASP.NET application. A server can have multiple web.config files, each existing in application roots or directories within the application. Settings in a web.config file either override or add new settings to the default configuration information provided by machine.config . Later in the chapter, you will learn how the administrator can control the settings that a web.config file is allowed to override.

We will come back to these configuration files soon and talk more about how to use them. Let's take a quick look at ASP configuration (for those who used ASP).

ASP Configuration

Prior to ASP.NET, ASP web application configuration was either accomplished by a script that modified the IIS metabase or through the IIS Manager.

Note

The metabase is a binary data store that IIS uses for configuration settings.

Let's use a common task (of setting session state timeout from 20 minutes to 10 minutes) to illustrate ASP configuration.

Session State Example

To configure session timeout in ASP, we go through the following steps (note these steps need to repeat for each server in your server farm):

1. Open the Internet Services Manager.

2. Right-click on a web application and select Properties.

3. Select the Home Directory tab.

4. Select Configuration.

5. Select the App Options tab.

Finally, you are presented with a dialog box in which you can configure session settings, as shown in Figure 13-1:

Figure 13-1:

You can change the session timeout value from 20 minutes to 10 minutes, press OK, and back out of all the menus . These settings are applied to the metabase, but they don't apply to your application just yet.

To apply these changes to the web application, you need to stop and start the web server by either using the IIS Manager (Stop and Start buttons ), or opening a command prompt and running iisreset .

Once these changes have been applied and IIS is restarted, the application has the desired behavior of 10-minute session timeout. If you maintain a web server farm, you need to manually perform these steps for each server.

Ideally, you could replicate the IIS metabase to all the servers in our farm, but due to security reasons, the metabase uses a unique machine key to encrypt some of the stored values. Even if you managed to copy the updated metabase to another server, that server would most likely not be able to use it. This method is not ideal, especially when running a web server farm!

Note

Application Center can replicate IIS settings to other IIS servers in your farm. Additionally, it includes other web farm manageability tools.

ASP.NET Configuration

For completeness, we need to show the same configuration example of setting session timeout from 20 minutes to 10 minutes for an ASP.NET application.

Session State Example

Fire up your favorite text editor and type the following XML into a file:

  <configuration>   <system.web>   <sessionState timeout="10" />   </system.web>   </configuration>  

Save this file as web.config in a web application root (see Chapter 12 for details on creating a web application).

Note

While ASP.NET does not use the IIS metabase for application settings, the administrator is still required to mark folders as web applications.

That's all there is to it “ the ASP.NET application will now timeout the Session after 10 minutes of inactivity. Similar to ASP, ASP.NET default session timeout is set to 20 minutes. Although not shown, this default value is set in the server's machine.config file. However, our web.config has overridden that setting to 10 minutes.

Note

Settings such as session timeout made in the IIS metabase via the IIS MMC, as done for the ASP example, do not effect your ASP.NET applications.

To update servers in the farm with these new settings, simply copy this web.config file to the appropriate application directory. ASP.NET takes care of the rest “ no server restarts and no local server access is required “ and your application continues to function normally, except now with the new settings. As you can clearly see, this new configuration system is very simple and straightforward to use. You simply write a configuration file and save it to a web application, and ASP.NET will automatically apply the changes. More on how all this works later.

Benefits of ASP.NET Configuration

As demonstrated in the preceding section, instead of relying on the metabase for application configuration information, ASP.NET uses XML configuration files. The benefits of this include:

• Human-readable configuration settings :It is very easy to open an XML file and read (or change) the settings. Tools that work with XML, such as Visual Studio .NET can be used to open the file and settings can easily be identified and updated.

• Updates are immediate :Unlike ASP, application configuration changes are immediate and do not require the web server to be stopped and restarted for the settings to take effect. Instead, the settings immediately affect a running system and are completely transparent to the end user .

• Local server access is not required :ASP.NET automatically detects when updates are made to the configuration system, and then creates a new instance of the application. End users are then redirected to the new application and the configuration changes are applied without the need for the administrator to stop and start the web server. Note that this is completely transparent to the end user. Although not covered in great detail, this is done through a CLR feature called application domains , mentioned in the previous chapter.

• Easy replication :Unlike the metabase, which could not easily be replicated since the instance of the metabase is bound to the server it resides upon, ASP.NET configuration files can simply be copied to the appropriate location “ they are simply XML files.

The ASP.NET configuration system eliminates 99 percent of the work to be done by the metabase. However, there are two exceptions:

• Creating web applications :As discussed in the previous chapter, marking a folder, either virtual or physical, through the Internet Service Management Console as an application allows ASP.NET to treat components , files, and configuration information as a web application. This process must still be accomplished either by using script that modifies the IIS metabase, through the IIS Manager snap-in, or automatically when you create a new ASP.NET project with Visual Studio .NET. The task of marking a web application forces the administrator to decide what is or is not an ASP.NET application.

• Custom file extension mappings :Again, as discussed in the previous chapter, if you wish to use file extensions other than those already supported by ASP.NET, you need to add an entry in the application settings for IIS. For example, to write applications that use the .wrox extension, you have to tell IIS that requests for resources ending with the .wrox extension should be handled by ASP.NET.

Both these exceptions are configuration decisions made when building the server. For all other application and server configuration options, such as configuring Session timeout, the execution timeout (how long an ASP.NET application executes before being timed out), or new settings such as timing out the worker process, we will use the ASP.NET configuration exclusively.

How Configuration Is Applied

When ASP.NET applies configuration settings for a given request, a union of the machine.config and any web.config files is applied for a given application. Configuration settings are inherited from parent web applications; machine.config being the root parent. This is depicted in Figure 13-2:

Figure 13-2:

The preceding screenshot is of the IIS MMC. The machine.config is applied to all web applications on the server. We then see callouts labeled web.config that identify locations where a web.config file might exist within this server. The three configuration files apply to:

• The root of the web “ for example, http://localhost/.

• A sub-application “ for example, http://localhost/7035/.

• A folder within the Wrox application “ for example, http://localhost/7035/configuration/Session/.

The configuration for each of these applications is unique, but settings are inherited. For example, if the web.config file in the root of the web site defines session timeout as 10 minutes (overriding the server's default settings inherited from machine.config ) and the web.config files in /7035/ and /7035/configuration/Session/ directories do not override these settings, both these directories will inherit the settings of 10 minute session timeout, in addition to applying their own settings for their respective application.

Detecting Configuration File Changes

ASP.NET detects when files (such as machine.config or web.config) are changed, by listening for file change notification events provided by the operating system. Behind the scenes, when an ASP.NET application is started, the configuration settings are read and stored in the ASP.NET Cache . A file dependency is then placed upon the entry within the Cache upon the machine.config and/or web.config configuration files. When a change is detected , such as an update to machine.config , ASP.NET creates a new application domain to service new requests. When the old application domain has completed servicing its outstanding requests, it is destroyed .

Note

An application domain is a feature provided by the CLR, and was discussed in the previous chapter.

There is no longer any need to stop and start IIS to apply configuration settings as with ASP. Instead, changes to ASP.NET configuration are immediate, and are handled behind the scenes through the use of application domains.

Configuration Is Extensible

What happens if your application has configuration data you'd like to store? This wasn't a feasible option in ASP (using the metabase), but with ASP.NET configuration, there are a couple of choices:

• High-level extension :You can use the application settings section of ASP.NET configuration.

(discussed later in the chapter) to store key/value pairs representing the configuration settings.

• Low-level extension :A more advanced option, discussed at the end of the chapter, is to create a custom configuration handler. A custom configuration handler allows you to extend the ASP.NET configuration system and process your own configuration settings.

We have discussed ASP.NET configuration at a high-level “ let's dig into the technical details.

Configuration File Format

As previously mentioned, there are two types of XML configuration files used by ASP.NET: machine.config and web.config . These two configuration files differ only in filename, where they live on the file system, and support of some settings. Both use the same XML format (pseudoschema shown):

Note

Items in brackets [] have unique values within the real configuration file.

  <?xml version="1.0" encoding="UTF-8"?>   <configuration>   <configSections>   <section name="[  sectionSettings  ]" type="[  Class  ]"/>     <sectionGroup name="[  sectionGroup  ]">   <section name="[  sectionSettings  ]" type="[  Class  ]"/>   </sectionGroup>   </configSections>     <[  sectionSettings  ] attribute="[  value  ]"/>     <[  sectionSettings  ] attribute="[  value  ]">   <element attribute="[  value  ]"/>   </[  sectionSettings  ]>     <[  sectionGroup  ]>   <[  sectionSettings  ] attribute="[  value  ]"/>     <[  sectionSettings  ] attribute="[  value  ]">   <element attribute="[  value  ]"/>   </[  sectionSettings  ]>   </[  sectionGroup  ]>   </configuration>  

Note

Note the camel- casing . The first letter of the first word is always lowercase and the first letter of subsequent words is uppercase “ for example, thisIsAnExample . Understanding the casing is very important, since the ASP.NET configuration system is case-sensitive.

The root element of the configuration file is always <configuration> . Within <configuration> there are two important sections:

• <section name="[sectionSettings]"> :Referred to as a configuration section handler, this defines a class used to interpret the meaning of configuration data. It is important to note that configuration section handlers only need to be declared once for all applications if declared in machine.config (this is because applications inherit the settings in machine.config ). Web applications that wish to change the settings for a particular configuration option, such as the Session example shown earlier, do not need to re-declare the configuration section handler.

• <[sectionSettings]> :Referred to as configuration section settings, this defines the actual settings for a particular option. The sample web.config file shown earlier defines a configuration section setting for sessionState overriding the default of 20 minutes inherited from machine.config .

These two sections are intimately related . Whereas section settings, such as configuring the timeout value for Session state, define options for a particular feature, section handlers define the code that implements the desired behaviors. We will look at some examples that clarify this.

Each of the section handlers and settings are optionally wrapped in a <sectionGroup> . A <sectionGroup> provides an organizational function within the configuration file. It allows you to organize configuration into unique groups “ for instance, the <system.web> section group is used to identify areas within the configuration file specific to ASP.NET.

Configuration Handlers

Section handlers identify .NET classes, which are loaded when the configuration system is loaded. These classes are responsible for reading the settings for their respective features from the configuration section settings.

The name attribute of the <section name="[sectionSettings]"> tag defines the tag name (here, sessionState ) of the configuration section settings element, ( <sessionState> ). Let's use the Session state example to better illustrate how this works.

Session State Example

Within the machine.config file, you can find the base definition for the sessionState section handler. Remember, since this section handler is defined in machine.config , you don't need to redeclare it on each use in web.config files.

Here is the XML that defines the sessionState section handler (highlighted):

 <?xml version="1.0" encoding="UTF-8" ?> <configuration>    <configSections>       <sectionGroup name="system.web">  <section name="sessionState"   type="System.Web.SessionState.SessionStateSectionHandler, System.Web,   Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"   allowDefinition="MachineToApplication"   />  </sectionGroup>    </configSections> ... 

The type="System.WebSessionState.SessionStateSectionHandler" identifies the class responsible for the configuration settings of ASP.NET session state. The name="sessionState" value defines the name of configuration section settings <sessionState> here, an element found later in the configuration document and System.Web identifies the assembly the class resides within.

Once a configuration section handler is declared, it does not need to be redeclared in configuration files that inherit from it. Since all web.config application configuration files inherit from machine.config , any configuration section handlers declared in machine.config are automatically available within web.config . In other words, <sessionState> settings may be declared in any application's web.config file and will be processed using the handler defined in machine.config .

You can enforce settings found in the machine.config so that web.config files can't override settings. For example, if you are running ASP.NET in a hosted environment, the administrator can restrict the sessionState settings so they can't be changed in web.config files “ we'll explore this option later in the chapter in the advanced topics section.

Let's take a look at the section settings that actually define our desired behaviors. We will use the same sessionState example.

Configuration Settings

The second section of the configuration file is the configuration session settings. Whereas the handler (described in the preceding section) names a class, the configuration session settings identify properties that affect the behavior of the application. In most cases, you only need to understand the settings for the configuration option you wish to modify, such as the settings for sessionState .

Again, this is best explained through revisiting the earlier session state example.

Session State Example

Here, we have the machine.config section handler and settings for ASP.NET sessionState “ the settings are highlighted. We will come back to the values for <sessionState> later:

 <?xml version="1.0" encoding="UTF-8" ?> <configuration>    <configSections>       <sectionGroup name="system.web">          <section name="sessionState"             type="System.Web.SessionState.SessionStateSectionHandler, System.Web,             Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a"             allowDefinition="MachineToApplication"             />          </sectionGroup>       ...    </configSections>    ...  <system.web>   <sessionState   mode="InProc"   stateConnectionString="tcpip=127.0.0.1:42424"   stateNetworkTimeout="10"   sqlConnectionString="data source=127.0.0.1; user id=sa;password="   cookieless="false"   timeout="20"   />   </system.web>  </configuration> 

In the session settings, sessionState properties are set “ for example, mode , cookieless , timeout , and so on. ASP.NET Session uses these settings, and when a request is made, ASP.NET knows where to find the necessary resources, as well as how to use those resources. For example, if you were to set cookieless to "true" , this would instruct ASP.NET to not use HTTP cookies to manage the Session ID and instead pass a key in the URL.

The preceding example showed both section handlers and session settings. As mentioned earlier, we will use the settings most often as web.config files that we build for our applications, to inherit the handlers and settings found in machine.config . The following code is a valid web.config file that enables cookieless session ID management “ note that the handler isn't being redeclared:

  <configuration>   <system.web>   <sessionState   mode="InProc"   stateConnectionString="tcpip=127.0.0.1:42424"   stateNetworkTimeout="10"   sqlConnectionString="data source=127.0.0.1; user id=sa;password="   cookieless="true"   timeout="20"   />   </system.web>   </configuration>  

It is good, but not absolutely necessary, to understand section handlers “ we will build our own at the end of the chapter. However, it is very important that you understand the settings. When we build and deploy applications, we will usually create our own web.config files and override the machine.config settings without seeing machine.config . It is recommended to modify web.config files rather than the machine.config , since changing machine.config affects all applications on the server. Let's discuss the most common configuration settings used for our applications.