ASP NET in a Nutshell 2nd Edition-ASP NET in a Nutshell 2nd Edition

20.2 web.config Elements

<configuration>

<configuration>
</configuration>

The root element for all configuration files; it is required.

Scope

All

Attributes

None

<appSettings>

<appSettings>
</appSettings>

The <appSettings> element can be used to configure custom application settings as key/value pairs. These settings can later be retrieved at runtime using the AppSettings property of the ConfigurationSettings class, as shown in the example. This property is shared (static) and does not require the ConfigurationSettings class to be instantiated before accessing the property.

Scope

Any

Attributes

None

Child Elements

<add>: The key/value pair to add.
<remove>: The key to remove.
<clear>: Clears all previously added key/value pairs.

Example

The following web.config section sets an application level key/value pair:

<configuration>
   <appSettings>
      <add key="applicationConfigKey" value="bar"/>
   </appSettings>
</configuration>

The following ASP.NET page retrieves the value set by the preceding code and also retrieves a value set at the machine.config level:

<%@ Page Language="VB" %>
<html>
<head>
   <script runat="server">
      Sub Page_Load( )
         Message1.Text &= _
            ConfigurationSettings.AppSettings("machineConfigKey")
         Message2.Text &= _
            ConfigurationSettings.AppSettings("applicationConfigKey")
      End Sub
   </script>
</head>
<body>
   <asp:label id="Message1" runat="server">Machine.Config setting: </ asp:label>
   <br/>
   <asp:label id="Message2" runat="server">Web.Config setting: </ asp:label>
</body>
</html>

Notes

As shown in the example, the <appSettings> element can be used separately from the <system.web> element and its children.

For security reasons, use caution when deciding what kinds of data to store using the <appSettings> element. Remember that while the ASP.NET runtime is set up to prevent an application's web.config file from being requested or read, this file could still be vulnerable if the security of the web server were breached in some other way. Thus, you should generally avoid storing sensitive information such as usernames and passwords, or connection strings containing usernames and passwords, in the web.config file. A better, although still moderately vulnerable, alternative is to store this information at the machine.config level, since this file is not within the web space of the application and is not as vulnerable to compromise through attacks on IIS. However, remember that this information will be available to any application on the machine.

<system.web>

<system.web>
</system.web>

Container element for all elements used in web.config files.

Scope

All

Attributes

None

Child Elements

Notes

This element is required in order to use any of its child elements.

<authentication>

<authentication>
</authentication>

Provides attributes and contains child elements used to configure authentication options in ASP.NET.

Scope

Machine, Application

Attribute

Mode

Determines the type of authentication that will be used by ASP.NET. Valid values are as follows:

Windows (default): Uses credentials provided by IIS authentication methods (Basic, Digest, Integrated Windows Authentication, or Certificates) to authenticate user requests. Requests can then be permitted or denied based on settings contained within the <authorization> element, using the authenticated username (or an associated group/role name) to allow or deny the request. This is the default authentication mode defined in machine.config.
Forms: Provides an infrastructure for performing custom authentication in situations when Windows authentication is not possible. When Forms authentication is enabled, users who have not logged in are automatically redirected to a login URL provided as an attribute of the <forms> element. Once logged in, a cookie is sent as an authentication token. Users can be authenticated against any credentials database the developer chooses—from Active Directory to a custom credentials database. This mode requires the inclusion of the <forms> child element.
Passport: Takes advantage of Microsoft's Passport authentication service. This mode requires inclusion of the <passport> child element.
None: Specifies that no authentication be performed at the ASP.NET level. Requests can still be authenticated at the IIS level using one of the IIS authentication modes in combination with NTFS access control lists (ACLs).

Child Elements

Example

The example configures the pages within the scope of the configuration file to use ASP.NET forms-based authentication:

<configuration>
   <system.web>
      <authentication mode="Forms">
         <forms name="myAuthCookie"
            loginUrl="login.aspx" 
            protection="All"
            timeout="30" 
            path="/" />
      </authentication>
   </system.web>
</configuration>

Notes

The <location> element can be used to configure authentication at the machine level, if desired, and its allowOverride attribute can be used to prevent overriding these settings in individual applications.

Authentication can be a fairly involved topic. For more information on the various ASP.NET authentication methods and how they relate to IIS authentication, please see Chapter 9.

<forms>

<forms
  loginUrl=String
  name=String
  path=String
  protection="All|None|Encryption|Validation"
  requireSsl=boolean
  slidingExpiration=boolean
  timeout=Integer>
</forms>

Provides attributes and one child element (<credentials>) to configure ASP.NET to use forms-based authentication.

Scope

Machine, Application

Attributes

name

Specifies the name of the authentication cookie. If this attribute is omitted, the value defaults to .ASPXAUTH. When running multiple applications that use forms-based authentication on the same server, it's usually a good idea to give each application its own authentication cookie name—to minimize the risk of authenticated users from one application being treated as authenticated in others.

loginUrl

Specifies the redirect URL for users who do not have a valid authentication cookie. If a user with no authentication cookie requests a page in the application, they will be redirected to this URL to log in. The login page can then redirect the user back to the originally requested page. If this attribute is omitted, the value defaults to login.aspx.

protection

Specifies the type of protection used to prevent the authentication cookie from being modified during transit. Valid values are as follows:

All: Cookies are both encrypted (using triple DES encryption, if available) and subjected to data validation. Data validation is performed based on the settings of the <machineKey> element. All is the default value and is the recommended setting for securing the authentication cookie.
Encryption: Cookies are only encrypted. This reduces overhead associated with cookie protection, but may leave cookies vulnerable to plain-text attacks.
None: Neither encryption nor validation is enabled for cookie protection. This reduces overhead when using forms-based authentication, but provides no protection of the authentication cookie. This attribute is not recommended.
Validation: A validation key is concatenated with cookie data. This key is checked to ensure that cookie data has not been altered in transit.

requireSsl

When set to True, prevents compliant browsers from sending the authentication cookie unless the connection is using SSL encryption. The default value is False. This attribute is only supported in Version 1.1 of ASP.NET.

slidingExpiration

When set to True, each request within the same session will reset the timeout value for the authentication cookie. The default value is True. This attribute is supported only in Version 1.1 of ASP.NET.

timeout

Specifies the amount of time, in minutes, before the authentication cookie expires. This is a sliding value, which is reset when a request is received after more than half of the timeout period has elapsed. Note that this attribute does not apply to persistent cookies. The default value is 30.

path

Specifies the path for the authentication cookie. Because many browsers treat the path in a case-sensitive manner, the default is set to the backslash (\) character.

Child Elements

Example

See the example for the <authentication> element.

Notes

Forms-based authentication is only effective when used in conjunction with the <authorization> element to deny anonymous users access to pages within the application.

It's a good idea to use SSL encryption to protect the forms authentication credentials and cookie to prevent the possibility of these credentials being hijacked. If you can't (or don't want to) use SSL, you should at least reduce the default timeout value to lessen the likelihood of someone capturing and impersonating the authentication cookie.

<credentials>

<credentials
 passwordFormat="Clear|SHA1|MD5">
</credentials>

Allows you to store one or more sets of credentials in the application (or machine) configuration file for later use in authenticating requests. The child <user> element is used to store the actual credentials.

Scope

Machine, Application

Attribute

passwordFormat: Specifies the format in which passwords will be stored (and compared). Valid options are Clear, SHA1, and MD5.

Child Elements

<user>

Example

The example shows the <credentials> element, which is used to store two user accounts to authenticate against:

<credentials passwordFormat = "SHA1">
   <user name="foo" password="794ED3D18464BAFF93F8DED1CFD00D9A2D9FE316"/>
   <user name="bar" password="B7CDD2A2B0F05E6948E5CEED22FA9A38EB28DEC8"/>
</credentials>

Notes

Once you've stored the credentials, you can authenticate against them by calling the static (shared) Authenticate method of the FormsAuthentication helper class. You can use the static (shared) HashPasswordForStoringInConfigFile method of FormsAuthentication to create an MD5 or SHA1 hash of the password for storing in the <user> element. When using the <credentials> element to store credentials, you should always hash passwords, since storing them in readable text presents a potential security risk. Although theoretically, no one should be able to read the configuration file, a server misconfiguration or security vulnerability could conceivably expose this file.

<user>

Stores the username and password for each user defined in the <credentials> element.

Scope

Machine, Application

Attributes

name: The username to be authenticated against.
password: The password to be authenticated against.

Child Elements

None

Example

See the example for the <credentials> element.

Notes

You should always use the HashPasswordForStoringInConfigFile method to hash passwords stored in the password attribute. A utility page that creates SHA1 or MD5 hashes of plain text passwords is provided in the examples for Chapter 9.

<passport>

<passport redirectUrl=Url />

This optional element configures an internal URL to which unauthenticated requests will be redirected when using Microsoft's Passport authentication provider. This element should be used only when the <authentication> element's mode attribute is set to Passport.

Scope

Machine, Application

Attributes

redirectUrl: A URL in the application to which requests lacking a Passport authentication token are redirected.

Child Elements

None

Example

This example shows a web.config file that configures an application for Passport authentication:

<configuration>
   <system.web>
      <authentication mode="Passport">
         <passport redirectUrl="Login.aspx"/>
      </authentication>
   </system.web>
</configuration>

Notes

For more information on configuring Passport authentication, see the Passport SDK documentation, which is available from http://www.passport.com.

<authorization>

Provides two child elements, <allow> and <deny>, that allow you to configure the users, roles, or HTTP verbs that can be used to access application resources.

Scope

Any

Attributes

None

Child Elements

Example

The example allows users Mary and John to access application resources using any HTTP verb, while denying POST access to nonauthenticated users:

<configuration>
   <system.web>
      <authorization>
         <allow users="Mary, John" />
         <deny users="?" verbs="POST" />
      </authorization>
   </system.web>
</configuration>

Notes

The type of authorization implemented by the <authorization> element is referred to as URL authorization. You can read more about URL authorization in Chapter 9.

You can specify authorization settings for a specific file or directory in your application that differs from the defaults configured in the root web.config file for the application in either of two ways:

By adding an <authorization> element to the web.config file of the desired child directory, as shown in the example.

By using a <location> tag in the root web.config file and setting its path attribute to the desired path, as follows:

<configuration>
   <location path="files">
      <system.web>
         <authorization>
            <deny users="?" />
         </authorization>
      </system.web>
   </location>
   <system.web>
      <!--other configuration settings -->
   </system.web>
</configuration>

<allow>

Specifies users, roles, and/or HTTP verbs to be authorized for the application.

Scope

Any

Attributes

users: A comma-delimited list of authorized usernames.
roles: A comma-delimited list of authorized roles (NT groups).
verbs: A comma-delimited list of authorized HTTP verbs (GET, HEAD, POST, or DEBUG).

Child Elements

None

Example

See the example for the <authorization> element.

Notes

You can use two wildcards to specify special groups of users:

*: When used for the value of the user attribute, allows access for all users. This is the default configuration setting, as defined in machine.config.
?: When used for the value of the user attribute, allows access to anonymous users. This wildcard is more commonly used with the <deny> element.

<deny>

Specifies users, roles, and/or HTTP verbs to be denied authorization for the application.

Scope

Any

Attributes

users: A comma-delimited list of authorized usernames.
roles: A comma-delimited list of authorized roles (NT groups).
verbs: A comma-delimited list of authorized HTTP verbs (GET, HEAD, POST, or DEBUG).

Child Elements

None

Example

See the example for the <authorization> element.

Notes

The same wildcards used by the <allow> element also apply to the deny element. To deny access to anonymous (non-authenticated) users, set the value of the users attribute of the <deny> element to ?.

<browserCaps>

<browserCaps>
 <result type=className />
 <use var=serverVarName />
 property1=value
 property2=value
 propertyN=value
 <filter match=string>
 property1=value
 property2=value
 propertyN=value
 </filter>
 <filter match=string>
 <filter match=string with=expressionToSearch>
 property1=value
 property2=value
 propertyN=value
 </filter>
 </filter>
 <filter>
 <case match=string>
 property1=value
 property2=value
 propertyN=value
 </case>
 <case match=string>
 property1=value
 property2=value
 propertyN=value
 </case>
 </filter>
</browserCaps>

Controls the configuration of the browser capabilities component returned by the Response.Browser property. The property/value pairs under the <use> element configure the default values of the browser capabilities component properties; the property/value pairs in the <filter> elements update these properties based on a match between the string value specified for the match attribute of the <case> element and the value of the var attribute of the <use> element (which is typically set to HTTP_USER_AGENT).

Scope

Any

Attributes

None

Child Elements

Example

The machine.config configuration file contains the default settings for the <browserCaps> element. The default settings provide the best example for modifying or updating this element.

Notes

The primary purpose of this configuration element and its children is to allow the addition of new browser types and to update the capabilities of these browsers. Thus, when a page calls the browser capabilities component, it will receive accurate information about the capabilities of the browser used for the current request.

<result>

<result type=className />

Specifies the class.

Scope

Any

Attribute

type: The class name, and optionally, version, culture, and key information that specifies the class that will contain the results of the browser capabilities analysis. This class must derive from HttpCapabilitiesBase. The default (set in machine.config) is System.Web.HttpBrowserCapabilities.

Child Elements

None

Notes

The default type of System.Web.HttpBrowserCapabilities is fine in most cases. If you want to add additional properties beyond those defined by the HttpBrowserCapabilities class, you can create your own class (derived from HttpCapabilitiesBase or HttpBrowserCapabilities) and use the <result> element to substitute it.

<use>

<use var=serverVariableName as=aliasName />

Sets the name of the server variable to use when evaluating browser capabilities.

Scope

Any

Attributes

var: The name of the server variable to use. The default is HTTP_USER_AGENT.
as: The string containing a name by which the server variable can be referenced in <case> elements and regular expressions.

Child Elements

None

Notes

The <use> element is followed by property/value pairs that specify the default properties for the browser capabilities component if no match is found with a <filter> element's match attribute (or that of its child <case> element). This usage is demonstrated in the entry for the <browserCaps> element.

<filter>

<filter match=string>
 property1=value
 property2=value
 propertyN=value
</filter>
<filter match=string>
 <filter match=string with=expressionToSearch>
 property1=value
 property2=value
 propertyN=value
 </filter>
</filter>
<filter>
 <case match=string>
 property1=value
 property2=value
 propertyN=value
 </case>
 <case match=string>
 property1=value
 property2=value
 propertyN=value
 </case>
</filter>

Specifies a regular expression pattern to search for in the server variable given in the <use> element (or optionally, another expression). Multiple <filter> elements can be contained in the <browserCaps> element; likewise, each <filter> element can contain <case> elements or other <filter> elements. All property assignments for matching <filter> elements will be executed, regardless of their order.

Scope

Any

Attributes

match: The pattern to match. Uses .NET Framework regular expression syntax. This attribute is optional. If omitted, all requests will be assumed to match and any property/value assignments contained within the <filter> element will be executed.
with: The regular expression or string to find. This attribute is optional. If omitted, the server variable specified in the <use> element will be searched.

Child Elements

<case>

Notes

The fact that <filter> elements can be nested makes them very flexible in terms of locating subsets of information. For example, the default <browserCaps> element in machine.config uses nested <filter> elements to locate both the major and minor browser versions contained in the HTTP_USER_AGENT server variable so that it can assign specific properties that vary among minor versions (i.e., the x in 4.x) of a browser.

<case>

<case match=string>
 property1=value
 property2=value
 propertyN=value
</case>

Specifies one of a group of exclusive matching cases for which property assignments will be executed. Only the first matching <case> element within a given <filter> element will be executed. The rest will be ignored.

Scope

Any

Attributes

match: The pattern to match. Uses the .NET Framework regular expression syntax. This attribute is optional. If omitted, all requests will be assumed to match, and any property/value assignments contained within the <filter> element will be executed.
with: The regular expression or string to find. This attribute is optional. If omitted, the server variable specified in the <use> element will be searched.

Child Elements

None

Notes

This element is useful in situations when you only want a single match. For example, the default <browserCaps> configuration in machine.config uses the <case> element to assign the platform, win16, and win32 attributes.

<clientTarget>

<clientTarget>
 <add alias=aliasName 
 userAgent=userAgentString />
 <remove alias=aliasName />
 <clear />
</clientTarget>

Assigns aliases for specified browser user agent strings to be used by ASP.NET Server Controls in deciding what type of content to render.

Scope

Any

Attributes

None

Child Elements

<add>: Adds an alias with the name specified by the alias attribute for the User Agent string specified by the userAgent attribute.
<remove>: Removes a previously configured alias with the name specified by the alias attribute.
<clear>: Clears all previously configured aliases.

Example

This example comes from the default <clientTarget> element:

<clientTarget>
   <add alias="ie5"
      userAgent="Mozilla/4.0 (compatible; MSIE 5.5; Windows NT 4.0)" />
   <add alias="ie4"
      userAgent="Mozilla/4.0 (compatible; MSIE 4.0; Windows NT 4.0)" />
   <add alias="uplevel"
      userAgent="Mozilla/4.0 (compatible; MSIE 4.0; Windows NT 4.0)" />
   <add alias="downlevel"
      userAgent="Unknown" />
</clientTarget>

Notes

This element is used primarily by the built-in ASP.NET Server Controls. Thus, you should avoid making changes to the existing aliases to avoid preventing these controls from rendering uplevel content.

<compilation>

<compilation  
 batch=boolean 
 batchTimeout=numSeconds 
 debug=boolean  
 defaultLanguage=languageAlias 
 explicit=boolean  
 maxBatchSize=maxPages 
 maxBatchGeneratedFileSize=maxSize 
 numRecompilesBeforeAppRestart=numRecompiles 
 strict=boolean 
 tempDirectory=dirName > 
 <compilers> 
 <compiler language=languageAlias 
 extension=fileExt 
 type=typeName  
 warningLevel=number  
 compilerOptions=optionString /> 
 </compilers> 
 <assemblies> 
 <add assembly=assemblyName /> 
 <remove assembly=assemblyName /> 
 <clear /> </assemblies>
</compilation>

Provides attributes and child elements for configuring the compilation options of ASP.NET applications. All attributes are optional.

Scope

Any

Attributes

batch: Specifies whether ASP.NET should attempt to batch compile all pages in the application when the first request for a page is made. The default is True.
batchTimeout: Specifies the amount of time, in seconds, that the compiler will spend attempting to batch compile pages in the application. If the timeout is exceeded, pages will be compiled as they are requested for the first time. The default is 15.
debug: Specifies whether pages will be compiled with debug symbols. The default is False.
defaultLanguage: Specifies the language compiler that will be used to compile inline code in ASP.NET pages for which no language is specified. The default is VB (Visual Basic .NET).
explicit: Specifies whether the Visual Basic .NET Option Explicit compiler option is enabled. The default is True.
maxBatchSize: Specifies the maximum number of classes generated during batch compilation. The default is 1000.
maxBatchGeneratedFileSize: Specifies the maximum combined size in KB of generated source files created during batch compilation. The default is 3000.
numRecompilesBeforeAppRestart: Specifies the number of recompiles before the appDomain containing the application is cycled (a new appDomain is created and the old one is torn down). The default is 15.
strict: Specifies whether the Visual Basic .NET Option Strict compiler option (which disallows implicit narrowing conversions) is enabled. The default is False.
tempDirectory: Specifies the directory in which temporary files from dynamically compiled code for the application will be stored. The default is %windir%\Microsoft.NET\Framework\%version%\Temporary ASP.NET Files.

Child Elements

Example

The example enables the Visual Basic .NET Option Strict compiler option and disables batch compilation:

<configuration>
   <system.web>
      <compilation
         batch="false"
         strict="true">
      </compilation>
   </system.web>
</configuration>

Notes

Make sure you understand the impact of changes to this element before making modifications. For example, setting the debug attribute to True will have a significant negative impact on performance. While setting the strict attribute to True will reduce the likelihood of bugs from implicit data type conversion, it could also increase the number of compiler errors you get while developing your code.

<assemblies>

<assemblies> 
 <add assembly=assemblyInfo /> 
 <remove assembly=assemblyInfo /> 
 <clear />
</assemblies>

Adds or removes assemblies to be referenced and linked during dynamic compilation of ASP.NET pages. By default, the mscorlib, System, System.Drawing, System.EnterpriseServices, System.Web, System.Data, System.Web.Services, and System.Xml assemblies are referenced during dynamic compilation, as are any assemblies located in the application directory's bin subdirectory.

Scope

Any

Attributes

None

Child Elements

<add>: Adds an assembly specified by the assembly attribute to the list of assemblies to be linked during dynamic resource compilation.
<remove>: Removes a previously configured assembly specified by the assembly attribute from the list of assemblies to be linked during dynamic resource compilation.

<clear>

Clears all previously configured assemblies.

Example

This example shows the <add> element used by the Mobile Internet Toolkit to add the assembly System.Web.Mobile to the list of assemblies for dynamic compilation:

<assemblies>
   <add assembly="System.Web.Mobile,
      Version=1.0.3300.0,
      Culture=neutral,
      PublicKeyToken=b03f5f7f11d50a3a" />
</assemblies>

Notes

The asterisk (*) wildcard is used with the <add> element to indicate that all assemblies in the application's private assembly cache (by default, the bin subdirectory of the application) should be added to the list of assemblies linked during dynamic compilation. This ensures that all members of these assemblies will be available to all the pages in your application automatically.

<compilers>

<compilers>
 <compiler language=languageAlias
 extension=fileExt
 type=typeName 
 warningLevel=number 
 compilerOptions=optionString />
</compilers>

Contains one or more <compiler> elements, each of which defines configuration options for a particular compiler to be used with ASP.NET.

Scope

Any

Attributes

None

Child Elements

Notes

Thanks to the <compilers> and <compiler> elements, adding support for a new .NET language in ASP.NET is as simple as adding a new <compiler> element specifying the language aliases, the file extension for class files for the language, and the type information for the language compiler.

<compiler>

<compiler language=languageAlias
 extension=fileExt
 type=typeName 
 warningLevel=number 
 compilerOptions=optionString />

Specifies configuration options for a given language.

Scope

Any

Attributes

language: Specifies the name or names by which the language will be specified in the language attribute of the @ Page directive. Multiple names should be separated by semicolons. This attribute is required.
extension: Specifies the extension(s) used by code-behind files for the specified language. Multiple entries should be separated by semicolons. This attribute is required.
type: Specifies the .NET type information for the class to be used to compile resources for the specified language. This attribute is required.
warningLevel: Specifies the compiler warning level for the language. This attribute is optional and may not be supported for all compilers.
compilerOptions: Specifies a string containing valid compiler options to be passed to the compiler.

Child Elements

None

Notes

The <compilers> element in machine.config provides a good example of the use of this element. Review that configuration section to see how the Visual Basic .NET, C#, and JScript .NET compilers are configured.

<customErrors>

<customErrors 
 defaultRedirect=Url
 mode=mode >
 <error statusCode=httpStatusCode
 redirect=Url />
</customErrors>

Specifies one or more pages to which users should be redirected if an unhandled exception is detected in an ASP.NET application. A default error page can be specified, as well as one or more error pages for specific HTTP error codes.

Scope

Any

Attributes

defaultRedirect: Specifies the URL of the page to which all errors should be redirected when no specific error page is configured for the HTTP status code of the error. This attribute is optional.
mode: Specifies the custom errors mode. Valid values are Off, On, and RemoteOnly. Off disables custom error handling, On enables custom error pages for both local and remote requests. RemoteOnly enables custom error pages for remote requests, while sending detailed error messages for local requests. This attribute is required.

Child Elements

<error>

Example

The example configures a default page to be displayed to remote clients when an unhandled exception is encountered:

<configuration>
   <system.web>
      <customErrors
         defaultRedirect="Error.aspx" />
   </system.web>
</configuration>

Notes

If you set the mode attribute to RemoteOnly, you will only be able to see detailed error information from the local machine on which the pages are running. Remote requests will return the custom error page (if any) configured for the status code of the error that occurred.

If you want to see the debug information provided by ASP.NET when an error occurs, the mode attribute should be set to Off.

<error>

<error statusCode=httpStatusCode
 redirect=Url />

Specifies a custom error page to handle redirections for a specific HTTP status code.

Scope

Any

Attributes

statusCode: Specifies the HTTP status code (such as 404 for a "Not Found" error) for the specified custom error page. This attribute is optional.
redirect: Specifies the URL of the page to which requests with a matching HTTP status code should be redirected. This attribute is optional.

Child Elements

None

Example

The example configures a custom error page for 404 errors, and the default error page configured in the previous example:

<configuration>
   <system.web>
      <customErrors
         defaultRedirect="Error.aspx">
         <error statusCode="404" redirect="My404ErrorPage.aspx"/>
      </customErrors>
   </system.web>
</configuration>

Notes

While custom error pages provide a convenient way to prevent users from seeing raw error messages (and perhaps provide more helpful messages), they are not a substitute for proper exception handling. By the time an error reaches a custom error page, recovering from the error gracefully will be much more difficult, which can degrade the experience of your users.

<globalization>

<globalization 
 requestEncoding=encodingString
 responseEncoding=encodingString
 fileEncoding=encodingString
 culture=cultureString
 uiCulture=cultureString />

Provides attributes for configuring encoding and culture settings. These attributes are used as the basis for the expected encoding of requests, responses, and files for internationalization.

Scope

Any

Attributes

requestEncoding: Specifies the assumed encoding of incoming requests. This can be any valid encoding string and should match the responseEncoding attribute. The default is UTF-8. This attribute is optional.
responseEncoding: Specifies the content encoding of responses. This can be any valid encoding string and should match the requestEncoding attribute. The default is UTF-8. This attribute is optional.
fileEncoding: Specifies the encoding used to parse .aspx, .asmx, and .asax files. This attribute is optional.
culture: Specifies the assumed culture for incoming requests. The value can be any valid culture string. This attribute is optional.
uiCulture: Specifies the culture for locale-specific resource searches. The value can be any valid culture string. This attribute is optional.

Child Elements

None

Example

This example shows how the default <globalization> settings are configured in web.config:

<configuration>
   <system.web>
      <globalization
         requestEncoding="utf-8"
         responseEncoding="utf-8" />
   </system.web>
</configuration>

Notes

A list of valid culture strings can be found in the .NET Framework documentation for the System.Globalization.CultureInfo class.

<httpHandlers>

<httpHandlers>
 <add verb=httpVerbs 
 path=pathInfo 
 type=typeInfo 
 validate=boolean />
 <remove verb=httpVerbs 
 path=pathInfo />
 <clear />
</httpHandlers>

Adds or removes HttpHandlers, which are used to provide request processing for a specified HTTP verb and/or file type or path. ASP.NET itself is set up as an HttpHandler for .aspx and .asmx files, and HttpHandlers are used to prevent downloading of source code for other ASP.NET file types, such as global.asax.

Scope

Any

Attributes

None

Child Elements

<add>: Adds an HttpHandler. The HTTP verbs (GET, POST, etc.) handled by the HttpHandler are specified by the verb attribute; the asterisk (*) wildcard is used to specify all verbs. The path or file extension to be handled by the HttpHandler is specified by the path attribute. The class used to process the request is specified by the type attribute. This class must implement the IHttpHandler interface. Finally, the validate attribute tells ASP.NET whether or not to attempt to load the class specified by the type attribute before a matching request comes in.
<remove>: Removes a previously configured HttpHandler, based on the specified verb and path attributes. The attributes must match a previously configured <add> element.
<clear>: Clears all previously configured HttpHandlers.

Example

The example configures a custom HttpHandler for the file extension .aspnetian:

<configuration>
   <system.web>
      <httpHandlers>
         <add verb="*" 
            path="*.aspnetian" 
            type="aspnetian.aspnetianHandler" />
      </httpHandlers>
   </system.web>
</configuration>

Notes

To make the example work properly, you need to map the file extension .aspnetian to the ASP.NET ISAPI handler, Otherwise, the request would never be handed to the custom HttpHandler. Chapter 9 has a step-by-step walkthrough of the process for mapping additional file types to the ASP.NET ISAPI handler.

<httpModules>

<httpModules>
 <add 
 name=moduleName 
 type=typeInfo />
 <remove name=moduleName />
 <clear />
</httpModules>

Adds or removes HttpModules. HttpModules are special classes that participate in the processing of all application requests. Both ASP.NET caching and session state are implemented as HttpModules, as are the authentication and authorization features of ASP.NET.

Scope

Any

Attributes

None

Child Elements

<add>: Adds an HttpModule. The class that implements the HttpModule is specified by the type attribute. This class must implement the IHttpModule interface. The name attribute provides an alias by which the HttpModule can be referenced—for example, in a later <remove> element.
<remove>: Removes a previously configured HttpModule, based on the specified name attribute. The attribute must match a previously configured <add> element.
<clear>: Clears all previously configured HttpModules.

Example

The example removes the HttpModule for the Session state provider, which can be useful if you're not using it:

<configuration>
   <system.web>
      <httpModules>
         <remove name="Session" />
      </httpModules>
   </system.web>
</configuration>

Notes

If you're not using a particular HttpModule, such as the Session state module or authentication modules, you may be able to save overhead by removing these HttpModules from an application's web.config file by using the <remove> element.

<httpRuntime>

<httpRuntime
 appRequestQueueLimit=numRequests
 enableVersionHeader=boolean
 executionTimeout=numSeconds
 maxRequestLength=numKBytes
 minFreeLocalRequestFreeThreads=numThreads 
 minFreeThreads=numThreads
 useFullyQualifiedRedirectUrl=boolean />

Contains attributes used to configure the settings for the ASP.NET HTTP runtime.

Scope

Any

Attributes

appRequestQueueLimit: Specifies the upper limit for request queuing. Once this limit has been reached, additional requests will receive a response of "503 - Server Too Busy." The default is 100.
enableVersionHeader: Specifies whether a special X-AspNet-Version header is sent with each request. The default is True. This attribute is only supported in Version 1.1 of ASP.NET.
executionTimeout: Specifies the amount of time, in seconds, that a request can execute before being terminated by the runtime. The default is 90.
maxRequestLength: Specifies the maximum file size, in KB, that can be uploaded by a client to an ASP.NET application. This attribute is used primarily to prevent denial of launched service attacks by attempting to upload very large files to the server. The default is 4096.
minLocalRequestFreeThreads: Specifies the minimum number of threads that will be reserved for requests from the local host that require additional threads. The default is 4.
minFreeThreads: Specifies the minimum number of threads that will be reserved for requests that require additional threads. The default is 8.
useFullyQualifiedRedirectUrl: Specifies whether URLs sent to the client for redirects are fully qualified or relative. The default is False, which specifies that the URL is relative.

Child Elements

None

Example

This example forces client-side redirect URLs to be fully qualified, which is required for some of the mobile controls supplied in the Microsoft Mobile Internet Toolkit:

<configuration>
   <system.web>
      <httpRuntime
         useFullyQualifiedRedirectUrl="true" />
   </system.web>
</configuration>

Notes

One of the most commonly customized attributes is maxRequestLength, since for sites that need to upload files, 4MB can be fairly limiting. Use caution when increasing this value, however; only increase it as much as necessary for the maximum file size you expect. Making this value too large can make your site vulnerable to denial-of-service attacks.

<identity>

<identity
 impersonate=boolean
 userName=string
 password=string />

Specifies whether request impersonation is enabled, as well as the identity to be used for requests made from the ASP.NET worker process and the password for that identity.

Scope

Any

Attributes

impersonate: Specifies whether impersonation is enabled for the application. If True, requests made by the ASP.NET worker process will be made with the security context of the account specified by the userName attribute; if that attribute is blank, the context of the account of the logged-in user. The default is False.
userName: Specifies the username of the Windows account to use for impersonation. If the value is left blank or is omitted, requests will be made in the context of the logged-in user.
password: Specifies the password for the account named in the userName attribute. This password is stored in clear text.

Child Elements

None

Example

The example turns on impersonation for the logged-in user authenticated by IIS:

<configuration>
   <system.web>
      <identity
         impersonate="true"
         userName="" />
   </system.web>
</configuration>

Notes

Because the password attribute stores passwords in readable text, you should carefully consider whether it makes sense to use this functionality. Storing sensitive information, such as passwords, in text files presents a potential security risk.

Recently, Microsoft has made a fix available for ASP.NET that will allow encrypted credentials for this element to be stored in the system registry for a higher level of security. You can find out more about this fix, as well as a utility for encrypting credentials, at the following URLs:

http://support.microsoft.com/default.aspx?scid=kb;EN-US;329250

http://support.microsoft.com/default.aspx?scid=kb;en-us;329290

<machineKey>

<machineKey
 validationKey="autogenerate|value"
 decryptionKey="autogenerate|value"
 validation="SHA1|MD5|3DES" />

Specifies the settings for cryptographic keys used for validation and decryption of Forms Authentication cookies.

Scope

All

Attributes

validationKey: The key used for validation of forms authentication cookie data, MAC checking of ViewState, and session state cookies. The default is autogenerate, which generates and stores a random key. For web farm implementations, you can set this value to the same 40- to 128-character key value on each server to ensure that all servers can validate successfully.
decryptionKey: The key used for decryption of forms authentication cookie data. The default is autogenerate, which generates and stores a random key. For web farm implementations, you can set this value to the same 40- to 128-character key value on each server to ensure that all servers can validate successfully.
validation: Specifies the type of encryption used for data validation.

Child Elements

None

Notes

For web farms, ensuring that the validationKey and decryptionKey values are synchronized across all servers in the farm is important. If they are not synchronized, you may get errors in Forms Authentication, ViewState errors, or problems with session state.

<pages>

<pages
 buffer=boolean
 enableSessionState="true|false|ReadOnly"
 enableViewState=boolean
 enableViewStateMac=boolean
 autoEventWireup=boolean
 smartNavigation=boolean
 pageBaseType=typeInfo
 userControlBaseType=typeInfo 
 validateRequest=boolean />

Contains attributes used to configure the default settings for ASP.NET pages and user controls. These settings can be overridden by attributes on the @ Page or @ Control directive.

Scope

Any

Attributes

buffer: Specifies whether buffering of page output is on or off. The default is True.
enableSessionState: Specifies whether a page has access to the Session state module. Acceptable values include True, False, and ReadOnly. The default is True.
enableViewState: Specifies whether ViewState is enabled at the page level. The default is True.
enableViewStateMac: Specifies at the page level whether a machine authentication check (MAC) is performed on the ViewState hidden field. This specification can help identify client-side tampering with the ViewState. The default is True.
autoEventWireup: Specifies whether ASP.NET will automatically support specific page events, such as Page_Load. The default is True.
smartNavigation: Specifies whether the Smart Navigation feature, for which IE 5 or above provides support for posting back and refreshing only portions of a page, is turned on at the page level. The default is False.
pageBaseType: Specifies the base class from which all pages are derived. The default is System.Web.UI.Page.
userControlBaseType: Specifies the base class from which all user controls are derived. The default is System.Web.UI.UserControl.
validateRequest: Specifies whether ASP.NET will automatically check the Request object for potentially dangerous input. If dangerous input, such as HTML or script, is found, an exception of type HttpRequestValidationException is thrown. The default is True. This attribute is only supported in Version 1.1 of ASP.NET.

Child Elements

None

Example

The example disables both Session state and ViewState at the page level:

<configuration>
   <system.web>
      <pages
         enableSessionState="false"
         enableViewState="false" />
   </system.web>
</configuration>

Notes

The <pages> element is very useful for setting application-level (or folder-level) defaults for pages in your application. One possible use is to place pages that do not require access to session state in a separate folder and use the <pages> element to disable session state for that folder. In this case, a session will not be created for a user until the user requests a page in your application for which EnableSessionState is True.

The default setting of EnableViewStateMac is True. It's important to remember this because the MAC check uses the settings in the <machineKey> element to create an encrypted version of the ViewState hidden field. In a web farm scenario, the <machineKey> settings for each server in the farm must match. Otherwise, the MAC check will fail when a user's initial request is handled by one server, while a subsequent postback is handled by another server with different settings for <machineKey>.

<processModel>

<processModel
 enable=boolean
 timeout="Infinite"|HH:MM:SS
 idleTimeout="Infinite"|HH:MM:SS
 shutdownTimeout="Infinite"|HH:MM:SS
 requestLimit=numRequests
 requestQueueLimit="Infinite"|numRequests
 restartQueueLimit="Infinite"|numRequests
 memoryLimit=percentMemory
 cpuMask=cpuNumBitMask
 webGarden=boolean
 userName=username
 password=password
 cpuMask=cpuNumBitMask
 webGarden=boolean
 userName=username
 password=password
 logLevel="All|None|Errors"
 clientConnectedCheck=HH:MM:SS
 comAuthenticationLevel="Default|None|Connect|Call|Pkt|
 PktIntegrity|PktPrivacy"
 comImpersonationLevel="Default|Anonymous|Identify|Impersonate|
 Delegate"
 responseRestartDeadlockInterval="Infinite"|HH:MM:SS
 responseDeadlockInterval="Infinite"|HH:MM:SS
 maxWorkerThreads=numThreads
 maxIoThreads=numThreads 
 serverErrorMessageFile=fileName />

Contains attributes used to configure the ASP.NET worker process in IIS 5.

Scope

Machine only

Attributes

enable

Specifies whether the <processModel> settings are enabled. The default is True.

timeout

Specifies the life span, in the format hh:mm:ss, of the process. When this value expires, a new process is started and the current process is shut down. To disable the timeout, use the value Infinite. The default is Infinite.

idleTimeout

Specifies the life span of the process, when idle, in the format hh:mm:ss. When this value expires, the current process is shut down. To disable the timeout, use the value Infinite. The default is Infinite.

shutdownTimeout

Specifies the amount of time, in the format hh:mm:ss, that the process is given to shut down gracefully. When this value expires, the process will be killed. To disable the timeout, use the value Infinite. The default is 0:00:05.

requestLimit

Specifies the number of requests that can be served by the ASP.NET process before it is shut down and restarted. This attribute can be used to proactively restart the ASP.NET process to compensate for memory leaks or other problems that may be associated with legacy resources (such as COM components) that you need to use in your applications. The default is Infinite, which disables this feature.

requestQueueLimit

Specifies the number of requests that can be queued by ASP.NET before it is shut down and restarted. This attribute can be used proactively to remedy situations in which resource contention causes requests to be queued. The default is 5000.

restartQueueLimit

Specifies the number of requests that will remain in the request queue while a process restart based on the requestQueueLimit setting occurs. The default is 10.

memoryLimit

Specifies the upper limit, as a percentage, of the server's physical memory that the ASP.NET process will be allowed to use. If this value is exceeded, a new process will be started up and the current process will be shut down. The default is 60.

cpuMask

Used in web garden scenarios to specify the CPU or CPUs in a multiprocessor server that will run the ASP.NET process. This value is a bitmask. The default is 0xffffffff, which specifies that a worker process should be created for every CPU.

webGarden

Specifies whether web gardening, in which worker processes are tied to specific processors within a multiprocessor server, is enabled. The default is False.

userName

Specifies the identity under which the ASP.NET worker process will be run. This can be a valid NT account or one of two special values:

SYSTEM: Runs the ASP.NET process as the SYSTEM account, which is a highly privileged administrative account.
machine: Runs the ASP.NET process as the ASPNET account (installed with the .NET Framework), which is a special account with few privileges. This process is the default and provides superior out-of-the box security for web applications written with ASP.NET. Note that the documentation for the <processModel> element incorrectly states that SYSTEM is the default.

password

Specifies the password of the account specified by the userName attribute. Use the value AutoGenerate (the default) when using the SYSTEM or machine accounts.

logLevel

Specifies the type of process events that are logged to the NT event log. Valid values are as follows:

All: All process events will be logged.
Errors: Only errors will be logged; this is the default.
None: No process events will be logged.

clientConnectedCheck

Specifies the amount of time, in the format hh:mm:ss, that a request remains in the queue before the ASP.NET process checks to ensure that the client is still connected. The default is 0:00:05.

comAuthenticationLevel

Specifies the authentication level used for DCOM security. The default is Connect.

comImpersonationLevel

Specifies the authentication level used for COM security. The default is Impersonate.

responseRestartDeadlockInterval

Specifies the amount of time, in the format hh:mm:ss, that will be allowed to elapse between process restarts due to the responseDeadlockInterval attribute value. This specification prevents constant process cycling due to deadlocks. To disable this feature, use the value Infinite. The default is 0:09:00.

responseDeadlockInterval

Specifies the amount of time, in the format hh:mm:ss, that may elapse without a response when requests are queued. When this value expires, the process will be shut down and restarted. To disable this feature, use the value Infinite. The default is 0:03:00.

maxWorkerThreads

Specifies the upper limit for worker threads per CPU in the thread pool. The default is 25.

maxIoThreads

Specifies the upper limit for IO threads per CPU in the thread pool. The default is 25.

serverErrorMessageFile

Specifies the filename of a file to be displayed when a "Server Unavailable" error occurs.

Child Elements

None

Notes

In IIS 6 native mode, the settings in the <processModel> element will be ignored.

Because the settings in the <processModel> element are read by and applied to the unmanaged aspnet_isapi.dll handler that passes requests to the managed aspnet_wp.exe worker process (rather than by managed code), changes to the <processModel> element will not be applied until IIS is restarted.

Recently, Microsoft has made a fix available for ASP.NET that will allow encrypted credentials for the userName and password attributes of this element to be stored in the system registry for a higher level of security. You can find out more about this fix, as well as a utility for encrypting credentials at the following URLs:

http://support.microsoft.com/default.aspx?scid=kb;EN-US;329250

http://support.microsoft.com/default.aspx?scid=kb;en-us;329290

<securityPolicy>

<securityPolicy>
 <trustLevel
 name=trustLevelName
 policyFile=fileName />
</securityPolicy>

Configures mappings of trust names (used by the <trust> element) to security policy files. The security policy files contain elements that configure the code access security permissions that are specific to that trust level. <securityPolicy> can contain one or more <trustLevel> elements.

Scope

Machine, Application

Attributes

None

Child Element

<trustLevel>: Each <trustLevel> element maps a trust-level name to a specific policy file that implements the code access security permissions for that trust level. The name attribute specifies the name by which the trust level will be referred in the <trust> element, while the policyFile attribute specifies the name of the policy file to map to the name.

Example

This example comes from the default <securityPolicy> element in machine.config:

<securityPolicy>
   <trustLevel
      name="Full"
      policyFile="internal" />
   <trustLevel
      name="High"
      policyFile="web_hightrust.config" />
   <trustLevel
      name="Low"
      policyFile="web_lowtrust.config" />
   <trustLevel
      name="None"
      policyFile="web_notrust.config" />
</securityPolicy>

Notes

For a specific application, if you want to modify the code access security permissions applied, you could create a new CAS policy file and map that file to a custom trust level by using the <trustLevel> element. To implement the new security policy, you would add a <trust> element to the web.config file of the desired application and use it to specify the mapped policy file by name.

<sessionState>

<sessionState
 mode="Off|Inproc|StateServer|SQLServer"
 cookieless=boolean timeout=numMinutes
 stateNetworkTimeout=numSeconds
 stateConnectionString="tcpip=server:port"
 sqlConnectionString=connString />

Scope

Machine, Application

Attributes

mode

Specifies whether session state is enabled, and if so, how the state data will be stored. Valid values are as follows:

Off: The session state is disabled.
InProc: The session state data will be stored in memory on the local server. This is the same model as session state in classic ASP. This session state mode does not allow session state to be shared across servers in a web farm.
StateServer: The session state data will be stored in memory in a special NT state service on a designated state server. This session state mode allows session state to be shared across servers in a web farm.
SQLServer: The session state data will be stored in a special SQL Server database on a designated SQL Server. This session state mode allows session state to be shared across servers in a web farm. This mode also requires running a SQL query (which is included with the .NET Framework SDK) to set up the SQL Server database.

The default is InProc.

cookieless

Specifies whether or not cookies will be used to associate users with specific sessions. If set to True, the session identifier will be automatically munged into the URL for each request. This requires that your application use relative URLs to work correctly. The default is False.

timeout

Specifies the amount of time, in minutes, before the session will time out when inactive (no requests are received with that SessionID). The default is 20.

stateNetworkTimeout

Specifies the amount of time, in seconds, that network operations will time out when working with the StateServer session state mode. The default is 10.

stateConnectionString

Specifies the server name or IP address and TCP port number for the session state server when using StateServer mode. This attribute is required when the mode attribute is StateServer. The default is tcpip=127.0.0.1:42424.

sqlConnectionString

Specifies the SQL Server name and authentication credentials when using SQLServer session mode. This attribute is required when the mode attribute is SQLServer. The default is data source=127.0.0.1;user id=sa;password=. Where possible, this value should use trusted connections to avoid storing a SQL userID and password in the web.config or machine.config file. To support SQL Server state mode, you need to run the InstallSqlState.sql batch file on the target SQL server to create the ASPState database and its associated tables and stored procedures. This file is installed by default in the %windir%\Microsoft.NET\Framework\%version% folder.

Child Elements

None

Example

The example configures session state to run in SQL Server mode without cookies:

<configuration>
   <system.web>
      <sessionState
         mode="SQLServer"
         cookieless="true"
         sqlConnectionString="data source=myServer;trusted_ connection=true" />
   </system.web>
</configuration>

Notes

To use SQL Server mode with a trusted connection, the account identity of the ASP.NET worker process must have a login to the SQL Server database and must have permission to access the ASPState and TempDB databases. If you cannot use a trusted connection, you should create a special account specifically to access the state database, and use that account for the sqlConnectionString attribute.

Note that when using either of the out-of-process session state modes, it's wise to use the EnableSessionState attribute of the @ Page directive to disable session state for pages in your application that do not use it. Otherwise, these pages will make unnecessary cross-machine calls to retrieve unused session state information. If you have a page that reads session data but does not alter it, you can also set the EnableSessionState attribute to ReadOnly to avoid the cross-machine call to store updated session data.

<trace>

<trace
 enabled=boolean
 localOnly=boolean
 pageOutput=boolean
 requestLimit=numRequests 
 traceMode="SortByTime|SortByCategory" />

Scope

Any

Attributes

enabled: Specifies whether tracing is enabled. The default is False.
localOnly: Specifies whether or not trace output can be viewed by machines other than the local host. The default is True.
pageOutput: Specifies whether trace output is rendered to the page or stored in memory and made accessible by the special Trace.axd URL. Trace.axd maps to an HttpHandler that displays all currently stored traces for a given application. The default is False.
requestLimit: Specifies the number of requests that can be stored in the trace buffer read by Trace.axd. Once the total number of request traces specified by this attribute has been stored, no more traces will be stored until the trace log has been cleared. The page displayed by Trace.axd includes a link for clearing the trace log. The default is 10.
traceMode: Specifies the sort order of items in the Trace Information section of the trace. Valid values are SortByTime and SortByCategory. SortByCategory is useful when you are using Trace.Write and Trace.Warn with your own category names passed as parameters. The default is SortByTime.

Child Elements

None

Example

This example turns tracing on at the application level:

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

Notes

Chapter 10 provides an overview of how to use the trace functionality of ASP.NET.

<trust>

<trust
 level="Full|High|Medium|Low|Minimal"
 originUrl=URL />

Assigns a named trust level created with the <trustLevel> child element of the <securityPolicy> element to a machine, a site, or an application.

Scope

Machine, Application

Attributes

level: Specifies the trust level to be applied. This attribute can be any value defined by the <securityPolicy> element. The default is Full. This attribute is required.
originUrl: Specifies URL of origin of an application. This attribute allows classes such as WebRequest, which may need the origin host information for certain security permissions, to work properly. This attribute is optional.

Child Elements

None

Example

This example sets the application CAS permissions, based on a custom trust level:

<configuration>
   <system.web>
      <trust level="myTrustLevel" />
   </system.web>
</configuration>

Notes

Make sure that you understand the security implications of using custom security policy mappings before using this element. Incorrect permissions can cause major problems for your application.

The syntax shown at the beginning of this section is for Version 1.1 of the .NET Framework.

<location>

<location
 path=pathToConfigure
 allowOverride=boolean >
 <system.web>
 <!-- Configuration settings -->
 </system.web>
</location>

Allows you to prevent settings in machine.config or web.config from being overridden in child configuration files. You can also use it to configure settings for specific files or folders from a configuration file in a parent folder.

Scope

Any

Attributes

path: Specifies the path to the file or folder to which the configuration settings contained in the <location> tag pair should be applied.
allowOverride: Specifies whether child configuration files can override values configured within the <location> tag pair. This attribute locks down configuration settings (i.e., at the machine.config level) for which you want to enforce uniformity.

Child Element

<system.web>

Example

The example, if used in machine.config, would force all applications on the machine to use Windows authentication:

<configuration>
   <location
      allowOverride="false">
      <system.web>
         <authentication mode="Windows">
      </system.web>
   </location>
   <system.web>
      <!-- Other configuration settings -->
   </system.web>
</configuration>

Notes

This tag provides powerful control over configuration. In addition to the scenario of enforcing an authentication method across all applications, you can also use the path attribute to configure multiple child folders or files from the web.config file in the root of the application. Using this configuration can avoid having a large number of child web.config files to manage for a larger application.

[ Team LiB ]