8.2 Modifying Configuration Settings

The most important part of configuration for the web developer is, of course, understanding how to modify the configuration files to achieve the desired ends. Unfortunately, in the first release of the .NET Framework and Visual Studio .NET, there aren't any rich GUI tools for editing configuration files (which sounds like a great third-party opportunity). As a result, editing configuration files is not terribly straightforward. The next several examples illustrate the basic techniques for editing web.config files.

Remember that ASP.NET configuration files follow XML syntax rules, including case-sensitivity of element and attribute names. Element and attribute names in ASP.NET configuration files typically use camel casing, in which the first letter of the initial word is lowercase and the first letter of each subsequent word is uppercase.

Also note that some (but not all) attribute values are case-sensitive. While this case-sensitivity is specific to the ASP.NET implementation rather than to XML, it's still a good idea to follow the case used in the examples when modifying configuration files.

8.2.1 Modifying Trace Settings

Tracing is a nifty feature of ASP.NET that allows recording and viewing of a host of valuable information about page requests. Like the other configuration elements considered in this chapter, the <trace> element appears in machine.config to set machine-wide default values:

<!--
   trace Attributes:
      enabled="[true|false]" - Enable application tracing
      localOnly="[true|false]" - View trace results from localhost only
      pageOutput="[true|false]" - Display trace ouput on individual pages
      requestLimit="[number]" - Number of trace results available in
         trace.axd
      traceMode="[SortByTime|SortByCategory]" - Sorts trace result
         displays based on Time or Category
-->
<trace enabled="false" 
   localOnly="true" 
   pageOutput="false" 
   requestLimit="10" 
   traceMode="SortByTime"/>

The settings in machine.config turn tracing off by default, which is a good thing. Since tracing carries performance overhead, you should enable it only when you are actually using it—usually during development or troubleshooting of an ASP.NET application. You should rarely enable tracing on a deployed production application, both for performance reasons and also to avoid the possibility of trace information being viewed by site visitors. See Chapter 10 for a more detailed discussion of application tracing. Example 8-1 shows the <trace> element modified to enable tracing for an application, with trace output being displayed on each page.

Example 8-1. Enabling tracing

<configuration>
   <system.web>
      <trace enabled="true" 
         pageOutput="true"/>
   </system.web>
</configuration>

You can enable tracing by setting the enabled attribute to True and direct the trace output to the page by setting the pageOutput attribute to True. The attributes shown in Example 8-1 override the settings in machine.config (and any parent web.config file that contains a <trace> element), while the remaining attributes should retain their default values as set in machine.config.

8.2.2 Changing the Authentication Mode

Modifying the <authentication> element of web.config should give you a deeper look at how configuration files work. The <authentication> element is included in the machine.config file with the following default settings:

<!-- 
   authentication Attributes:
      mode="[Windows|Forms|Passport|None]"
-->
<authentication mode="Windows">
  
   <!--
      forms Attributes:
         name="[cookie name]" - Name of the cookie used for Forms
            Authentication
         loginUrl="[url]" - Url to redirect client to for Authentication
         protection="[All|None|Encryption|Validation]" - Protection mode
            for data in cookie
         timeout="[seconds]" - Duration of time for cookie to be valid 
            (reset on each request)
         path="/" - Sets the path for the cookie
   -->
   <forms name=".ASPXAUTH" loginUrl="login.aspx" protection="All" 
      timeout="30" path="/">
  
      <!--
         credentials Attributes:
            passwordFormat="[Clear|SHA1|MD5]" - format of user password
               value stored in <user>
      -->
      <credentials passwordFormat="SHA1">
         <!-- <user name="UserName" password="password"/> -->
      </credentials>
  
   </forms>
  
   <!--
      passport Attributes:
         redirectUrl=["url"] - Specifies the page to redirect to, if the
            page requires authentication, and the user has not signed on
            with passport
   -->
   <passport redirectUrl="internal"/>
  
</authentication>

These configuration settings give the machine-wide defaults for authentication in ASP.NET applications. Windows authentication is enabled by default. Note that for Windows authentication to function properly, some form of IIS authentication other than Anonymous must be enabled. The machine.config settings also specify defaults for the attributes of the <forms> element, which is used in Forms authentication, and for the <passport> element.

Notice that the formatting of the configuration settings denotes the parent/child relationships of the elements. Both the <forms> and <passport> elements are children of the <authentication> element, while the <credentials> element is the child of the <forms> element. The <user> element (commented out in the preceding code) is in turn the child of the <credentials> element.

You would see the <forms> element specified only in machine.config when the mode attribute of the <authentication> element is set to Windows, a setting that does not require any child elements. The reason for this is that these settings are used as defaults for various authentication methods. Supplying values for the attributes of the <forms> element at the machine level provides defaults that are inherited by any application using Forms authentication automatically, while any attribute values for the <forms> element contained in web.config files for specific applications override these settings.

Example 8-2 shows an <authentication> element for an application that uses Windows authentication. The <authorization> element is also shown. In this case, this element denies access to anonymous users, which forces authentication, if it has not already occurred.

Example 8-2. Windows authentication settings

<configuration>
   <system.web>
      <authentication mode="Windows"/>
      <authorization>
         <deny users="?"/>
      </authorization>
   </system.web>
<configuration>

Consider an application in which you want to use Forms authentication (discussed further in Chapter 9) to enable authentication against your own custom credential store. In this case, you would use an authentication element, such as that shown in Example 8-3, along with its child <forms> element, and the <authorization> element shown in Example 8-2. Note that the <forms> element is required only if you want to override the settings specified in machine.config. Example 8-3 specifies a different login page (myLogin.aspx) to which unauthenticated users are redirected.

Example 8-3. Forms authentication settings

<configuration>
   <system.web>
      <authentication mode="Forms">
         <forms loginUrl="myLogin.aspx"/>
      </authentication>
      <authorization>
         <deny users="?"/>
      </authorization>
   </system.web>
<configuration>

8.2.3 Configuring Out-of-Process Session State

The <sessionState> configuration element in machine.config sets the following machine-wide defaults:

<!-- sessionState Attributes:
   mode="[Off|InProc|StateServer|SQLServer]"
   stateConnectionString="tcpip=server:port"
   stateNetworkTimeout="timeout for network operations with State Server,
      in seconds"
   sqlConnectionString="valid System.Data.SqlClient.SqlConnection string,
      minus Initial Catalog"
   cookieless="[true|false]"
   timeout="timeout in minutes"
-->
<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"/>

Unlike the <authentication> element, the <sessionState> element has no children, only attributes. Like the <authentication> element, the usage of the <sessionState> element in machine.config contains a combination of attributes not normally seen in practice, since the purpose of the attributes is to set machine-wide defaults. For example, the default mode of in-process session state (InProc) requires no additional attributes to function. In fact, if you want to use InProc, you do not need to add a <sessionState> element to your web.config file at all. Examples Example 8-4 and Example 8-5 show the appropriate settings for the <sessionState> element for out-of-process session state using the ASP.NET state service and SQL Server session state, respectively.

Example 8-4. Out-of-process state with state service

<configuration>
   <system.web>
      <sessionState mode="StateServer" 
         stateConnectionString="tcpip=StateServerName:42424" 
         stateNetworkTimeout="30" />
   </system.web>
<configuration>

Example 8-4 sets the mode attribute to StateServer, which uses the ASP.NET state NT service installed with ASP.NET to store session state settings for multiple machines. This setting requires the stateConnectionString attribute; since the default setting of 127.0.0.1 (the local machine loopback address) is not terribly useful for sharing state information across multiple machines, you need to replace it with the name of the machine that is responsible for maintaining this information (StateServerName in the example).

In out-of-process session state scenarios, a single machine is designated to maintain session values for multiple ASP.NET servers. Therefore, each server using the shared session information should be configured to point to the same state server. To compensate for potential network latency issues, the example changes the default stateNetworkTimeout value of 10 seconds to 30 seconds. Note that inherent in this decision is a tradeoff between avoiding timeouts and potentially poorer application performance.

Inherent in either type of out-of-process session state is a substantial performance hit due to the need to cross process and/or machine boundaries to retrieve session state information. You should use out-of-process session state only when your need for scalability outweighs your need for absolute performance. You should also test the performance of your chosen session state mode with a tool such as the Microsoft Web Stress tool to ensure that it meets your performance and scalability needs.

Example 8-5. Out-of-process state with SQL Server

<configuration>
   <system.web>
      <sessionState mode="SQLServer" 
         sqlConnectionString="data source=ServerName;user id=name;password=pwd"
         cookieless="true"/>
   </system.web>
</configuration>

Example 8-5 sets the mode attribute to SQLServer, which uses an SQL Server database called ASPState to store session state values to be shared across multiple machines. This database is set up using the InstallSqlState. sql batch file installed by default in the directory %windir%\Microsoft.NET\Framework\%version%, where %windir% is the Windows directory and %version% is the version number of the installed framework (the version number is prefixed with a "v" in the actual path).

The SQLServer mode requires the use of the sqlConnectionString attribute. You should always override this attribute, since its default uses the local 127.0.0.1 loopback address and uses the SQL Server sa account to connect to the ASPState database. Neither is a good practice in a production application. In Example 8-5 set the data source portion of the connection string to the name of the designated SQL Server state machine and set the user ID and password to an account set up to read and write state data.

Example 8-5 also sets the cookieless attribute to True, anticipating that some users may have disabled cookies. Setting this attribute to True places the session identifier within the URL of all requests, allowing session use without cookies. Note that applications designed for cookieless sessions should use relative rather than absolute URLs for internal links.

A word on security: as noted previously, the default settings for sqlConnectionString use the SQL Server sa, or system administrator, account to connect to the ASPState database. This is not a good security practice. Instead, you should always set up a separate account that is purpose-specific (in this case, to read and write session state data) and use that account for connecting to the state database. You may even want to consider setting up a separate account for each ASP.NET application for this purpose; this allows you to track and audit access to the ASPState database on a per application basis more easily. These steps can help minimize the possibility of database security being compromised through over-permissive security settings.