ptg 1514 CHAPTER 34 Configuring Applications The Web Site Administration Tool has the following four tabs: . Home—Contains links to the other tabs. . Security—Enables you to configure authentication, authorization, and the Role Manager. . Application—Enables you to create and manage application settings, configure SMTP settings, and enable application tracing, debugging, and error pages. You also can use this tab to take your application offline. . Provider—Enables you to select a provider for Membership and the Role Manager. 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 404—Not 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 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-In You also can make configuration changes with IIS directly. The latest versions of Internet Information Services (IIS) have ASP.NET configuration options directly in the console. Previous versions of IIS had snap-in property sheets that provided limited configuration. When you click either a website or an application in the left-side browser, the following ASP.NET options are available for that selection: . .NET Authorization Rules . .NET Compilation . .NET Error Pages . .NET Globalization From the Library of Wow! eBook ptg 1515 Overview of Website Configuration . .NET Profile . .NET Trust Levels . Application Settings . Connection Strings . Machine Key . Pages and Controls . Session State . SMTP E-mail Behind the scenes, IIS is directly manipulating the Web.config files for sites and applica- tions. If you ever had to manually tweak some difficult settings in these files, then you can certainly appreciate that IIS now lets you make these changes directly within IIS (see Figure 34.2). 34 FIGURE 34.2 Configuration options available within IIS. ASP.NET Configuration Sections All 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: . anonymousIdentification—Enables you to configure anonymous user identification, which is used, for example, by the Profile object. . authentication—Enables you to configure authentication. . authorization—Enables you to configure authorization. From the Library of Wow! eBook ptg 1516 CHAPTER 34 Configuring Applications . browserCaps—Enables you to configure the lookup of browser capabilities. . caching—Enables you to configure caching policies. . clientTarget—Enables you to configure aliases for different clients (browsers). . compilation—Enables you to configure how ASP.NET applications are compiled. For example, you can specify whether an application is compiled in debug mode. . customErrors—Enables you to configure custom error pages. . deployment—Enables you to specify whether an ASP.NET application is deployed in retail mode. . deviceFilters—Enables you to configure device filters. . globalization—Enables you to configure the Culture, UICulture, and other attrib- utes related to building multilingual web applications. . healthMonitoring—Enables you to configure Health Monitoring. See the final section of this chapter. . hostingEnvironment—Enables you to configure ASP.NET application properties such as the application idle timeout. . httpCookies—Enables you to configure how cookies are sent to the browser. . httpHandlers—Enables you to configure HTTP Handlers. . httpRuntime—Enables you to configure properties of the HTTP Runtime, such as the number of threads maintained in the thread pool. . httpModules—Enables you to configure HTTP Modules. . identity—Enables you to configure the identity of the ASP.NET application account. . machineKey—Enables you to configure encryption keys used by Membership and Session state. . membership—Enables you to configure ASP.NET Membership. . mobileControls—Enables you to configure adapters used with ASP.NET mobile controls. . pages—Enables you to configure page properties such as the website Master Page and Theme. See Chapter 5, “Designing Websites with Master Pages,” and Chapter 6, “Designing Websites with Themes.” . processModel—Enables you to configure the ASP.NET process. . profile—Enables you to configure the Profile object. . roleManager—Enables you to configure the Role Manager. . securityPolicy—Enables you to map security policy files to trust levels. . sessionPageState—Enables you to configure how mobile devices store Session state. From the Library of Wow! eBook ptg 1517 Overview of Website Configuration . sessionState—Enables you to configure Session state. . siteMap—Enables you to configure Site Maps. . trace—Enables you to configure page and application tracing. . trust—Enables you to configure Code Access Security (CAS) for an ASP.NET applica- tion. . urlMappings—Enables you to remap page requests to new pages. . webControls—Enables you to specify the location of client-script files used by web controls. . webParts—Enables you to configure Web Parts. . webServices—Enables you to configure web services. . xhtmlConformance—Enables you to configure the level of XHTML conformance of the XHTML rendered by web controls. Applying Configuration Settings to a Particular Path By 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 configura- tion 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 34.1 enables password-protection for a single file named Secret.aspx. LISTING 34.1 Web.config <?xml version=”1.0”?> <configuration > <system.web> <authentication mode=”Forms” /> </system.web> <location path=”Secret.aspx”> <system.web> <authorization> <deny users=”?” /> </authorization> </system.web> </location> </configuration> 34 From the Library of Wow! eBook ptg 1518 CHAPTER 34 Configuring Applications 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 34.1 by right-clicking the project in Solution Explorer, choosing 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 IIS. Both tools enable you to enter values for the appSettings section through a user-friendly interface. Locking Configuration Settings You 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 executes 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. TIP As an alternative to locking the compilation section to prevent a production website being deployed in debug mode, you can take advantage of the deployment element. Adding the following element to the system.web section of the machine.config disables debug mode, enables remote custom errors, and disables trace: <deployment retail=”true” /> You can lock a configuration setting in multiple ways. The Web.config file in Listing 34.2 illustrates how you can lock a setting by using the allowOverride=”false” attribute of the <location> element. LISTING 34.2 Web.config <?xml version=”1.0”?> <configuration > <location allowOverride=”false”> <system.web> <compilation debug=”false” /> </system.web> From the Library of Wow! eBook ptg 1519 Overview of Website Configuration </location> </configuration> The configuration file in Listing 34.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 34.2, an exception is raised (see Figure 34.3). 34 FIGURE 34.3 Attempting to override a locked configuration section. One problem with the configuration file in Listing 34.2 is that it locks the entire compila- tion element. If you attempt to change any attribute of the compilation element at a lower level in the configuration hierarchy, 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: . lockAllAttributesExcept—Enables you to lock all attributes except those listed as the value of this attribute. You can specify multiple attributes to exclude in a comma-delimited list. . lockAllElementsExcept—Enables you to lock all child elements of the current element except those listed as the value of this attribute. You can specify multiple elements to exclude in a comma-delimited list. From the Library of Wow! eBook ptg 1520 CHAPTER 34 Configuring Applications . lockAttributes—Enables you to lock multiple attributes. You can specify the attrib- utes to lock in a comma-delimited list. . lockElements —Enables you to lock multiple child elements. You can specify the child elements to lock in a comma-delimited list. . lockItem—Enables you to lock the current element. For example, the web configuration file in Listing 34.3 locks the debug attribute, and only the debug attribute, of the <compilation> element. LISTING 34.3 Web.config <?xml version=”1.0”?> <configuration > <system.web> <compilation debug=”false” lockAttributes=”debug” /> </system.web> </configuration> Adding Custom Application Settings You can easily add custom configuration settings to the web configuration file by taking advantage of the appSettings section, which section contains a list of key and value pairs. For example, the web configuration file in Listing 34.4 contains a welcome message and a copyright notice. LISTING 34.4 Web.config <?xml version=”1.0”?> <configuration> <appSettings> <add key=”welcome” value=”Welcome to our Web site!” /> <add key=”copyright” value=”Copyright (c) 2007 by the company” /> </appSettings> </configuration> You can retrieve values from the appSettings section either programmatically or declara- tively. The page in Listing 34.5 illustrates both approaches (see Figure 34.4). From the Library of Wow! eBook ptg 1521 Overview of Website Configuration 34 LISTING 34.5 ShowAppSettings.aspx <%@ Page Language=”C#” %> <%@ Import Namespace=”System.Web.Configuration” %> <!DOCTYPE html PUBLIC “-//W3C//DTD XHTML 1.0 Transitional//EN” “http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd”> <script runat=”server”> void Page_Load() { lblWelcome.Text = WebConfigurationManager.AppSettings[“welcome”]; } </script> <html xmlns=”http://www.w3.org/1999/xhtml” > <head id=”Head1” runat=”server”> <title>Show AppSettings</title> </head> <body> <form id=”form1” runat=”server”> <div> FIGURE 34.4 Displaying values from the appSettings configuration section. From the Library of Wow! eBook ptg 1522 <asp:Label id=”lblWelcome” Runat=”server” /> <hr /> <asp:Literal id=”ltlCopyright” Text=”<%$ AppSettings:copyright %>” Runat=”server” /> </div> </form> </body> </html> In Listing 34.5, the welcome message is retrieved programmatically from the WebConfigurationManager.AppSettings property. The value retrieved is assigned to a Label control. 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 retrieves the value of the copy- right key: <%$ AppSettings: copyright %> Placing Configuration Settings in an External File You 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 sepa- rate 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 34.6 uses the configSource attribute in its <appSettings> element. LISTING 34.6 Web.config <?xml version=”1.0”?> <configuration> <appSettings configSource=”appSettings.config” /> </configuration> CHAPTER 34 Configuring Applications From the Library of Wow! eBook ptg 1523 Using the Configuration API 34 The appSettings are stored in the external file, as shown in Listing 34.7. LISTING 34.7 appSettings.config <?xml version=”1.0”?> <appSettings> <add key=”message” value=”Hello World!” /> </appSettings> Normally, modifying a web configuration file results in your ASP.NET application restart- ing. 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 34.6, for example, your application won’t restart. NOTE The book’s website 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.) Using the Configuration API The Configuration API enables you to retrieve and modify configuration settings. You can use the Configuration API to modify web configuration files on the local machine or a remote machine. If you are responsible for maintaining a large number of websites, the Configuration API can make your life much easier. You can build administrative tools that enable you to quickly make configuration changes to multiple applications. You can use the Configuration API in an ASP.NET page, or you can build command-line tools or Windows Forms applications that use the Configuration API. The Configuration API is exposed by the WebConfigurationManager class (located in the System.Web.Configuration namespace). This class supports the following properties: . AppSettings—Exposes all the settings from the appSettings section. . ConnectionStrings—Exposes all the settings from the connectionStrings section. From the Library of Wow! eBook . eBook ptg 1518 CHAPTER 34 Configuring Applications 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. 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. both approaches (see Figure 34. 4). From the Library of Wow! eBook ptg 1521 Overview of Website Configuration 34 LISTING 34. 5 ShowAppSettings.aspx <%@ Page Language=”C#” %> <%@ Import