Overview of Website Configuration
| ASP.NET uses a hierarchical system of configuration. At the top of the hierarchy is the Machine.config file. This file contains all the default configuration settings for ASP.NET applications and all other types of applications built with the .NET Framework. The Machine.config file is located at the following path: \WINDOWS\Microsoft.NET\Framework\[version]\CONFIG\Machine.config This same folder also contains a Web.config file. The Web.config file contains settings specific to ASP.NET applications. The Web.config file overrides particular settings in the Machine.config file. Note The \CONFIG folder includes the following six files:
Only the Machine.config and Web.config files are actually used. The other files are there for the purpose of documentation. You can place a Web.config file in the root folder of a website, such as the wwwroot folder. A Web.config file located in the root folder of a website contains settings that apply to all applications contained in the website. You also can place a Web.config file in the root of a particular application. In that case, the Web.config file has application scope. Finally, you can place a Web.config file in an application subfolder. In that case, the Web.config file applies to all pages in that folder and below. When an ASP.NET application starts, this hierarchy of configuration files is merged and cached in memory. A file dependency is created between the cached configuration settings and the file system. If you make a change to any of the configuration files in the hierarchy, the new configuration settings are loaded into memory automatically. When an ASP.NET page reads a configuration setting, the setting is read from memory. This means that the ASP.NET Framework can read configuration settings, such as connection strings, very efficiently. Furthermore, when you make a change to a configuration setting, you don't need to stop and restart an application manually for the new setting to take effect. The ASP.NET Framework reloads the cached configuration settings automatically when the configuration settings are changed on the file system. (The one exception to this is modifications to the processModel section.) Warning Modifying most configuration settings results in an application restart. Any data stored using the cache or in-process Session state is lost and must be reloaded. You can get around this issue by using external configuration files. See the section "Placing Configuration Settings in an External File" later in this chapter. The configuration files are XML files. You can modify configuration settings by opening the Machine.config file or a Web.config file and modifying a setting in Notepad. Alternatively, you can change many of the configuration settings (but not all) by using either the Web Site Administration Tool or the ASP.NET Microsoft Management Console Snap-In. Using the Web Site Administration ToolIf you are using Visual Web Developer (or Visual Studio .NET), then you can modify certain configuration settings with the Web Site Administration Tool. This tool provides you with a form interface for making configuration changes (see Figure 26.1). Figure 26.1. Opening the Web Site Administration Tool. You open the Web Site Administration Tool by selecting the menu option Website, ASP.NET Configuration. Selecting this option opens a browser window that contains the tool. Warning There is a bug in the first release of ASP.NET 2.0. If you open the Web Site Administration Tool, then you'll lose Intellisense when you open the Web.config file directly in Visual Web Developer. The Web Site Administration Tool adds an xmlns attribute to the opening <configuration> tag. If you want to get Intellisense working again, then you need to remove the xmlns attribute. The Web Site Administration Tool has the following four tabs:
Under the Application tab, you can click the link to take your application offline. When you click this link, the following httpRuntime element is added to your web configuration file: <httpRuntime enable="false" /> This setting causes the Application Domain associated with the ASP.NET application to refuse any requests. When an application is offline, all requests result in a 404Not Found error message. You might want to take your application offline, for example, to prevent people from requesting pages while you perform updates to your application. Note You also can take an ASP.NET application offline by adding a file with the name app_offline.htm to the root of your application. The Web Site Administration Tool is implemented as an ASP.NET application. Behind the scenes, it uses the Configuration API that is discussed later in this chapter. You can view the entire source code for the Web Site Administration Tool by navigating to the following folder: \WINDOWS\Microsoft.NET\Framework\[version]\ASP.NETWebAdminFiles Using the ASP.NET Microsoft Management Console Snap-InYou also can make configuration changes with the ASP.NET Microsoft Management Console (MMC) Snap-In tool (see Figure 26.2). You can open the ASP.NET MMC Snap-In by following these steps:
Figure 26.2. Using the ASP.NET Microsoft Management Console Snap-In. The ASP.NET MMC Snap-In includes the following tabs:
Behind the scenes, the ASP.NET MMC Snap-In uses the Configuration API to make changes to web configuration files. ASP.NET Configuration SectionsAll the configuration sections in the Machine.config or Web.config file related to ASP.NET are contained in the <system.web> section group. Here is a complete list of the 36 ASP.NET configuration sections and a brief explanation of the purpose of each section:
Applying Configuration Settings to a Particular PathBy default, the settings in a Machine.config or Web.config file are applied to all pages in the same folder and below. However, if you have the need, you can also apply configuration settings to a particular path. For example, you can apply configuration settings to a particular subfolder or even a particular page. You apply configuration settings to a particular path by using the <location> element. For example, the web configuration file in Listing 26.1 enables password-protection for a single file named Secret.aspx. Listing 26.1. Web.config
If you attempt to request the Secret.aspx page, you are redirected to the Login.aspx page. However, none of the other files in the same application are password protected by the configuration file. The <location> element must be added as an immediate child of the <configuration> element. You can't, for example, add the <location> element within a <system.web> element. You must surround the <system.web> element with the <location> element. Note You can create the web configuration file in Listing 26.1 by selecting the menu option Website, Add New Item, and selecting the Web Configuration File template. Alternatively, you can add the appSettings section by using either the Web Site Administration Tool or the ASP.NET MMC Snap-In. Both tools enable you to enter values for the appSettings section through a user-friendly interface. Locking Configuration SettingsYou can lock configuration settings so that they cannot be overridden at a lower level in the configuration hierarchy. For example, you might want to require that no application running on your production server execute in debug mode. In that case, you can lock the debug configuration setting in a website Web.config file, the root Web.config file, or the Machine.config file. You can lock a configuration setting in multiple ways. The Web.config file in Listing 26.2 illustrates how you can lock a setting by using the allowOverride="false" attribute of the <location> element. Listing 26.2. Web.config
The configuration file in Listing 26.2 locks the compilation element. If you attempt to add a configuration file that sets the debug attribute to the value true, and the configuration file is located below the configuration file in Listing 26.2, then an exception is raised (see Figure 26.3). Figure 26.3. Attempting to override a locked configuration section. One problem with the configuration file in Listing 26.2 is that it locks the entire compilation element. If you attempt to change any attribute of the compilation element at a lower level in the configuration hierarchy, then an exception is raised. You can add any of the following attributes to a particular configuration element to lock either the entire element or one or more of its attributes:
For example, the web configuration file in Listing 26.3 locks the debug attribute, and only the debug attribute, of the <compilation> element. Listing 26.3. Web.config
Adding Custom Application SettingsYou can add custom configuration settings to the web configuration file easily by taking advantage of the appSettings section. The appSettings section contains a list of key and value pairs. For example, the web configuration file in Listing 26.4 contains a welcome message and a copyright notice. Listing 26.4. Web.config
You can retrieve values from the appSettings section either programmatically or declaratively. The page in Listing 26.5 illustrates both approaches (see Figure 26.4). Figure 26.4. Displaying values from the appSettings configuration section. Listing 26.5. ShowAppSettings.aspx
In Listing 26.5, the welcome message is retrieved programmatically from the WebConfigurationManager.AppSettings property. The value retrieved is assigned to a Label control. Notice that the System.Web.Configuration namespace must be imported before you can use the WebConfigurationManager class. You retrieve the copyright notice declaratively by using the AppSettingsExpressionBuilder. The following expression is used to retrieve the value of the copyright key: <%$ AppSettings: copyright %> Placing Configuration Settings in an External FileYou can place particular configuration sections in an external file. You might want to do this for a couple of reasons. First, you can make a configuration file more manageable by dividing it into multiple files. Also, when you place configuration information in a separate file, you can prevent application restarts when you change a configuration setting. Every configuration element includes a configSource attribute. You can assign a path to a file as the value of the configSource attribute. For example, the web configuration file in Listing 26.6 uses the configSource attribute in its <appSettings> element. Listing 26.6. Web.config
The appSettings are stored in the external file in Listing 26.7. Listing 26.7. appSettings.config
Normally, modifying a web configuration file results in your ASP.NET application restarting. Any data stored in Session State or the Cache object is lost. However, the appSettings section is declared in the Machine.config file with a restartOnExternalChanges="false" attribute. This attribute prevents your application from restarting when a change is made to the appSettings section in an external configuration file. If you modify the file in Listing 26.6, for example, your application won't restart. Note The CD that accompanies this book includes a page named ShowAppStartTime.aspx, which displays the time that the current ASP.NET application started. You can use this file to detect when a modification made to a web configuration file caused an application restart. (The application start time is retrieved in the Application_Start() event handler in the Global.asax file.) |
