Application Configuration Files

The application configuration files ( web.config and the site-wide machine.config ) have had a number of changes, including new attributes added to existing elements as well as new elements to support the new features. The changed sections of the configuration files cover the topics listed below:

• Client targets

• Compilation

• Web proxy

• HTTP modules

• HTTP runtime

• HTTP handlers

• Globalization

• Pages

• Session state

• Web request modules

The new sections cover the following topics:

• Anonymous identification

• Code DOM

• Connection strings

• Data

• Caching

• Image generation

• HTTP cookies

• Membership

• Site maps

• Site counters

• Personalization

• Protocols

• Role Manager

• Mail servers

• URL mappings

• Web Administration Tool

Changed Sections

The text in this subsection details only the changes made to the configuration files and the changed attributes.

Client Targets

The <clientTarget/> section identifies browsers by their user agent string and provides a mapping to a simple alias. For the downlevel alias, the user agent has been changed from Unknown to Generic Downlevel , as shown below:

 <clientTarget>   <add alias="downlevel" userAgent="Generic Downlevel" /> </clientTarget> 

Compilation

The <compilation/> section has been enhanced to allow for automatic compilation of source files and pre-compilation of applications. For this there is a new <codeSubDirectories/> element that indicates which directories contain code that should be automatically compiled. This section contains a collection of relative directory names where code is placed. The syntax is shown below:

 <compilation   urlLinePragmas="[truefalse]"   >     <codeSubDirectories>       <add directoryName="  String  " />     </codeSubDirectories>   </compilation> 

There is also a new Boolean attribute on the main compilation section, urlLinePragmas . This indicates whether or not pragmas use URLs. The default is false , which means that pragmas use physical paths.

The <compilers/> section has been moved to the new <system . codedom /> section, which is covered later in the chapter.

Build Providers

The <buildProviders/> section identifies which files are part of the dynamic compilation process. The syntax for this section is:

 <buildProviders>   <add     extension="  String  "     appliesTo="  String  "     type="  String  " /> </buildProviders> 

The attributes are described in Table 13.1.

Table 13.1. buildProvider Attributes

Attribute	Description
extension	The file extension (e.g., .resx ) of the file to be built.
appliesTo	The directory (e.g., Resources ) where the files reside.
type	The type name of the build provider class used to invoke the compilation.

This section is for files that aren't part of the compilation section (those files are automatically built). Compilation and build providers were covered in Chapter 2.

Web Proxy

The <defaultProxy/> section defines how the System.Net classes access the Internet and has been enhanced to include the following settings:

 <defaultProxy   automaticallyDetectSettings="[truefalse]"   autoConfigurationScript="  String  "   scriptDownloadInterval="  Integer  "   scriptDownloadTimeout="  Integer  "   /> 

The attributes are described in Table 13.2.

Table 13.2. defaultProxy Attributes

Attribute	Description
automaticallyDetectSettings	Indicates whether or not discovery of the proxy server is automatic.
autoConfigurationScript	Indicates a URI that points to the proxy server configurations script.
scriptDownloadInterval	Defines, in seconds, the time that elapses before the configuration script is refreshed.
scriptDownloadTimeout	Defines, in seconds, the time allowed for the configuration script to download.

HTTP Modules

Several new HTTP modules have been added to the pipeline.

• SessionID allows generation of Session ID values to be factored out by programmers. This enables developers to easily provide their own Session ID values.

• RoleManager provides support for the Role Manager.

• AnonymousIdentification provides support for identification of anonymous visitors .

• Personalization provides support for Personalization.

• PageCountersModule provides support for the page counters.

A full description of these is beyond the scope of this book, but details can be found in the SDK documentation.

HTTP Runtime

The <httpRuntime/> section has been enhanced to cater to application domain shutdowns and buffered uploads, with the following new attributes:

 <httpRuntime   enable="[truefalse]"   idleTimeOut="  Integer  "   requestLengthDiskThreshold="  Integer  "   requireRootedSaveAsPath="[truefalse]"   /> 

The attributes are described in Table 13.3.

Table 13.3. httpRuntime Attributes

Attribute	Description
enable	Indicates whether or not the current application domain (and those below it) is enabled. The default value is true .
idleTimeOut	Indicates the life, in minutes, of the application domain before it is shut down (unless a debugger is attached to the application). The default value is 20 .
requestLengthDiskThreshold	Indicates the threshold, in kilobytes, for buffering the input stream; should not exceed the MaxRequestLength property. The default value is 256 .
requireRootedSaveAsPath	Indicates whether or not the path for Save As operations must be a rooted path . The default value is true .

The enable attribute allows an entire application domain to be disabled, perhaps in a hosting environment. Any requests to that application will result in a 404 error.

The addition of automatic shutdowns is useful for sites that are hit infrequently (such as personal sites, maybe a photo album), where keeping the application active wastes resources. The idleTimeOut figure indicates the number of minutes since the last request was received.

The requestLengthDiskThreshold and requireRootedSaveAsPath attributes are for file uploads. They define the maximum size of uploaded files and the path to where they can be saved, respectively.

HTTP Handlers

The <httpHandlers/> section has been enhanced to cater to the following new handlers:

• WebAdmin.axd , for the Web Administration Tool

• WebResource.axd , for Web resources

• CachedImageService.axd , for cached images

• Counters.axd , for site counters for URL redirection

• Precompile.axd , for site pre-compilation

In addition, the following file suffixes are handled by the forbidden handler ( System.Web.HttpForbiddenHandler ), stopping them being served directly:

• .master

• .skin

• .browser

• .mdb

• .vjsproj

• .java

• .jsl

Globalization

The <globalization/> section has one new attribute, to allow automatic setting of culture depending on the browser.

 <globalization   enableClientBasedCulture="[truefalse]"   /> 

This attribute indicates whether or not the uiCulture and culture will be based on the accept-language header sent by the client browser. This overrides culture settings in configuration files, unless the client cultures cannot be mapped to a specific culture. The default value is false .

Pages

The <pages/> section has been enhanced to add Personalization, master pages, and theme support. Additionally, there is a subelement that allows automatic addition of namespace references to each page (see Listing 13.1).

Listing 13.1 pages Configuration Syntax

 <pages   enablePersonalization="[truefalse]"   personalizationProvider="  String  "   master="  String  "   theme="  String  "   >   <namespaces>     <add namespace="  String  " />   </namespaces> </pages> 

The attributes are described in Table 13.4. Both the master and theme attributes can be overridden at the page level.

Table 13.4. pages Attributes

Attribute	Description
enablePersonalization	Indicates whether or not Personalization is enabled. The default value is false .
personalizationProvider	Defines the name of the provider for Personalization.
master	Defines the site-wide master page. This allows a master page to be applied to all pages without adding the master attribute to the Page directive.
theme	Defines the site-wide theme. This allows a theme to be applied to all pages without adding the theme attribute to the Page directive.

For the namespaces subelement, the namespace is the full namespace to be included as a reference. For example:

 <namespaces>   <add namespace="System" />   <add namespace="System.Collections" /> </namespaces> 

The following namespaces are included in machine.config :

• System

• System.Collections

• System.Collections.Specialized

• System.ComponentModel

• System.Configuration

• System.Text

• System.Text.RegularExpressions

• System.Web

• System.Web.Caching

• System.Web.SessionState

• System.Web.Security

• System.Web.Personalization

• System.Web.UI

• System.Web.UI.Imaging

• System.Web.UI.WebControls

• System.Web.UI.HtmlControls

Session State

There are several changes to the state handling mechanism, which are covered in detail later in the chapter. Here's the new syntax for the <sessionState/> section:

 <sessionState   mode="[OffInProcStateServerSQLServerCustom]"   sqlCommandTimeout="  Integer  "   customType="  String  "   cookieName="  String  "   createEmptySession="[truefalse]"   allowCustomSqlDatabase="[truefalse]"   /> 

The new attributes are described in Table 13.5.

Table 13.5. sessionState Attributes

Attribute	Description
mode	Indicates how session state is being managed. Can be one of the following values: Off : Indicates session state storage is disallowed . InProc : Indicates the session state is stored in the executing ASP.NET process. StateServer : Indicates that session state is stored in the external Windows Session State Service. SQLServer : Indicates that session state is stored in SQL Server. Custom : Indicates that session state is stored in a custom manner. The default value is InProc .
sqlCommandTimeout	Indicates, in seconds, the timeout for a SQL command when the mode is SQLServer . The default value is 30 .
customType	Indicates the full data type name of the class when the mode is Custom .
cookieName	Defines the default cookie name used to store the session ID.
createEmptySession	Indicates whether or not to create a new session even if it is empty.
allowCustomSqlDatabase	Indicates whether or not a custom database name can be specified in the Initial Catalog attribute of the SQL Server connection string.

Mobile Devices State

In addition to the session state changes, there is also a <sessionPageState/> element, which details the number of pages of session state stored on the server:

 <sessionPageState   historySize="  Integer  "   /> 

This works in a way similar to the session state management for mobile controls in the MMIT from ASP.NET 1.x. This is required because the session state is stored on the server, and without the history it would be possible for the session state to become out of sync with the displayed page. The default value is 9 .

Web Request Modules

When using the WebRequest class to access Web resources, you have the option of using HTTP, HTTPS, or FILE as the protocols. The <webRequestModule/> now has FTP added to provide file transfer support:

 <add prefix="ftp"   type="  String  "   /> 

The type attribute identifies the full type of the class implementing the service.

New Sections

The configuration files contain many new sections to cater to the new features in ASP.NET 2.0. These new sections are described briefly below.

Anonymous Identification

The <anonymousIdentification/> section deals with how identity is assigned to users who are not authenticated (see Listing 13.2). It is used by the Personalization services.

Listing 13.2 anonymousIdentification Configuration Syntax

 <anonymousIdentification   enabled="[truefalse]"   cookieName="  String  "   cookieTimeout="  Integer  "   cookiePath="  String  "   cookieRequiresSSL="[truefalse]"   cookieSlidingExpiration="[truefalse]"   cookieProtection="[NoneValidationEncryptionAll]"   cookieless="[UseCookiesUseUriAutoDetectUseDeviceProfile]"   /> 

The attributes are described in Table 13.6.

Table 13.6. anonymousIdentification Attributes

Attribute	Description
enabled	Indicates whether or not anonymous identification is enabled. The default value is false .
cookieName	Specifies the name of the cookie. The default value is .ASPXANONYMOUS .
cookieTimeout	Specifies the value, in minutes, before the cookie expires . This cannot be or less. The default value is 100000 .
cookiePath	Specifies the path, which is case-sensitive, used to write the cookie. Using '/' allows applications within the same domain to access the cookie. The default is '/' .
cookieRequiresSSL	Indicates whether or not the cookie requires an SSL connection in order to be written to the client. The default value is false .
cookieSlidingExpiration	Indicates whether the cookie timeout resets upon each request (a value of true) or expires at a fixed time (a value of false ). The default value is true .
cookieProtection	Specifies the protection scheme used to store the cookie. Can be one of the CookieProtection enumerations (from System.Web.Security ): None : Indicates no protection is used. Validation : Indicates that the cookie is hashed and validated . Encryption : Indicates that the cookie is encrypted. All : Indicates that both validation and encryption are used. The default value is None .
cookieless	Specifies the cookie scheme to use. Can be one of the following: UseUri : Forces the authentication ticket to be stored in the URL. UseCookies : Forces the authentication ticket to be stored in the cookie (same as ASP.NET 1.x behavior). AutoDetect : Automatically detects whether the browser/device supports cookies. UseDeviceProfile : Chooses to use cookies or not based on the device profile settings from machine.config . The default value is UseDeviceProfile .

Code DOM

The <system.codedom/> section has been introduced to centralize the configuration of compilation features across all aspects of the .NET Framework, rather than having them be part of the Web configuration. The <compilers/> element has been moved into this new section (see Listing 13.3).

Listing 13.3 system.codedom Configuration Syntax

 <system.codedom>   <compilers>     <compiler       language="  String  "       extension="  String  "       type="  String  "       warningLevel="  Integer  "       compilerOptions="  String  "     />   </compilers> </system.codedom> 

The attributes for each listed compiler are the same as the previous version, but with one addition, compilerOptions , which allows default compiler options to be set.

Connection Strings

The <connectionStrings/> section allows database connection strings to be stored. Previously these were often stored in the appSettings section and thus used to get mixed in with general application settings. Now, however, they have a specific section, allowing database details to be stored either at the application level or for the entire machine. This also allows the connection string details to be protected (perhaps by encryption), thus keeping them secure. Although this functionality isn't part of the current release, it is planned for future releases.

Table 13.7. connectionStrings Attributes

Attribute	Description
name	The name of the connection string.
connectionString	The full connection details. No validity checking is performed.

 <connectionStrings>   <add name="  String  "     connectionString="  String  "   />   <remove name="  String  " />   <clear /> </connectionStrings> 

The attributes are described in Table 13.7.

Like the application-specific settings, the connection strings are exposed through the ConfigurationSettings class. For example, we could define our database details as:

 <connectionStrings>   <add     name="MyData"     connectionString="server=.;database=MyData;Uid=;Pwd=" /> </connectionStrings> 

Then we could use these details in our page or class:

 Dim cs As String cs = ConfigurationSettings.ConnectionStrings("MyData") Dim conn As New SqlConnection(cs) 

Data

The <system.data/> section allows configuration of data provider factories, allowing for abstracted access to data stores (see Listing 13.4).

Listing 13.4 system.data Configuration Syntax

 <system.data>    <DbProviderFactories>      <add       name="  String  "       invariant="  String  "       support="  String  "       description="  String  "       type="  String  "       />   </DbProviderFactories> </system.data> 

The attributes for <DbProviderFactories/> are described in Table 13.8.

Table 13.8. DbProviderFactories Attributes

Attribute	Description
name	The name of the data factory.
invariant	The namespace of the data factory.
support	The level of support supplied by the provider. Can be a combination of items in the DbProviderSupportedClasses enumeration.
description	The description of the data factory.
type	The full type of the class that handles the factory.

The supplied data factories are for:

• Odbc

• OleDb

• OracleClient

• SqlClient

Caching

Caching is an area of ASP.NET that can bring great performance improvements, but one thing missing from ASP.NET 1.x was the capability to base the cache on a database. This capability would enable the cache to expire when the data it is caching changes, thus ensuring that out-of-date cached values are never used.

The new <cache/> section allows the cache dependency to be set and based on databases (see Listing 13.5). Initially only SQL Server is supported, but the architecture allows for others to be added in future releases.

Listing 13.5 cache Configuration Syntax

 <cache>   <sqlCacheDependency     enabled="[truefalse]"     pollTime="  Integer  "     >     <databases>       <add         name="  String  "         connectionName="  String  "         pollTime="  Integer  "         />       <remove         name="  String  "         />     </databases>   </sqlCacheDependency> </cache> 

The attributes are described in Tables 13.9 and 13.10.

For more details on caching, please see Chapter 11.

Table 13.9. sqlCacheDependency Attributes

Attribute	Description
enabled	Indicates whether or not the SQL cache dependency polling is enabled. The default value is true .
pollTime	Defines, in milliseconds , the poll time. The minimum value is 500 . The default value is 60000 .

Table 13.10. databases Attributes

Attribute	Description
name	The name of the database.
connectionName	The name of the connection string from the connectionStrings configuration section.
pollTime	The time, in milliseconds, between polls . If not specified, the pollTime from the parent element is used.

Image Generation

The <imageGeneration/> section allows configuration of the dynamic generation of images. The syntax is shown below:

 <imageGeneration   storageType="  String  "   storagePath="  String  "   storageExpiration="  Integer  "   /> 

The attributes are described in Table 13.11.

Table 13.11. imageGeneration Attributes

Attribute	Description
storageType	The type of storage to be used. This can be one of the StorageType enumerations from System.Web.UI.Imaging : Disk : Indicates storage on disk. Cache : Indicates storage in the cache. The default value is Cache
storagePath	If Disk storage is being used, this specifies the path where generated images will be stored. If not supplied, the ASPNETImageStorage directory is used, in the Temp directory of the ASPNET account.
storageExpiration	The default length of time, in seconds, before an image expires. The default value is 300 .

HTTP Cookies

The <httpCookies/> section controls whether certain HTTP headers are sent to the browser. This enables more secure storage of cookies and ensures that user-supplied code cannot access the cookies from the browser. Here's the syntax:

 <httpCookies   httpOnlyCookies="[truefalse]"   requireSSL="[truefalse]"   domain="  String  "   /> 

The attributes are described in Table 13.12.

Table 13.12. httpCookies Attributes

Attribute	Description
httpOnlyCookies	Indicates whether or not the HttpOnly cookie attribute is added to the page, to ensure that cookies cannot be accessed client side.
requireSSL	Indicates whether or not the secure cookie attribute is added to the page.
domain	Defines the domain to which the cookie applies, which sets the domain cookie attribute for the page.

Membership

The <membership/> section defines the configuration for the supplied Membership schemes. It follows the standard providers pattern, allowing custom providers to be supplied (see Listing 13.6).

Listing 13.6 membership Configuration Syntax

 <membership   defaultProvider="  String  "   userIsOnlineTimeWindow="  Integer  ">   <providers>     <add name="  String  "       type="  String  "       [  providerSpecificSettings  ]       />     <remove name="  String  "      />     <clear>   </providers> </membership> 

The attributes are described in Tables 13.13 and 13.14.

Table 13.13. membership Attributes

Attribute	Description
defaultProvider	The name of the default provider. There is no default value.
userIsOnlineTimeWindow	The time, in minutes, since last activity when the user was deemed to be online. The default value is 15 .
providerSpecificSettings	The settings specific to the provider.

Table 13.14. providers Attributes

Attribute	Description
name	The name of the membership provider. The default value is AspNetAccessProvider .
type	A string containing the full .NET type of the provider.
providerSpecificSettings	A name/value collection detailing provider-specific settings.

SQL Server and Access Membership Providers

Two providers are supplied with this release, giving support for SQL Server and Access databases. These are named AspNetSqlProvider and AspNetAccessProvider , respectively, and both have the same syntax for the provider-specific section:

 connectionStringName="  String  " enablePasswordRetrieval="[truefalse]" enablePasswordReset="[truefalse]" requiresQuestionAndAnswer="[truefalse]" applicationName="  String  " requiresUniqueEmail="[truefalse]" passwordFormat="[ClearHashedEncrypted]" description="  String  " 

The attributes are described in Table 13.15.

Table 13.15. SQL Server and Access Membership Provider Specific Attributes

Attribute	Description
connectionStringName	Specifies the name of the connection string, from the connectionStrings section.
enablePasswordRetrieval	Indicates whether or not the provider will allow retrieval of passwords. The default value is false .
enablePasswordReset	Indicates whether or not the provider will allow passwords to be reset. The default value is true .
requireQuestionAndAnswer	Indicates whether or not the provider enforces a question-and-answer method for retrieving forgotten passwords. The default value is false . Valid only when the passwordFormat setting is not Hashed and enablePasswordRetrieval is true .
applicationName	Defines the scope of the application. The default value is / .
requiresUniqueEmail	Indicates whether or not the provider enforces unique e-mail addresses. The default value is false .
passwordFormat	Defines how the passwords should be stored. Can be one of the following: Clear : For clear text passwords. Hashed : For hashed passwords. Encrypted : For encrypted passwords. The default value is Hashed .
description	Defines the description of the provider.

Membership is covered in detail in Chapter 6.

Site Maps

The <siteMap/> section allows configuration of site map providers, providing menuing and navigation features (see Listing 13.7).

Listing 13.7 sitemap Configuration Syntax

 <siteMap     defaultProvider="  String  "     enabled="[truefalse]">   <providers>     <add       name="  String  "       description="  String  "       type="  String  "       [  providerSpecificSettings  ]       />     <remove name="  String  "       />     <clear>   </providers> </siteMap> 

The attributes are described in Tables 13.16 and 13.17 on the next page.

Table 13.16. siteMap Attributes

Attribute	Description
defaultProvider	The name of the default provider. This should match one of the names supplied in the providers section. The default value is AspNetXmlSiteMapProvider .
enabled	A Boolean value indicating whether or not site maps are enabled. The default value is true .

Table 13.17. siteMap providers Attributes

Attribute	Description
name	The name of the site map provider.
description	A description of the provider
type	A string containing the full .NET type of the provider.
providerSpecificSettings	The provider-specific settings.

AspNetXmlSiteMapProvider

The supplied site provider is for XML files and has a single attribute, siteMapFile , which defines the name of the site map file. The default value for this is app.SiteMap .

Site Counters

The <siteCounters/> section defines the configuration for the site counters service, allowing tracking of navigation from server controls (see Listing 13.8).

Listing 13.8 siteCounters Configuration Syntax

 <siteCounters   enabled="[truefalse]"   defaultProvider="  String  "   handlerPath="  String  "   handlerType="  String  "   rowsPerDay="  Integer  "   type="  String  ">     <providers>       <add         name="  String  "         type="  String  "         [  providerSpecificSettings  ]         />       <remove         name="  String  " />       <clear/>     </providers>     <pageCounters       enabled="[truefalse]"       defaultProvider="  String  "       rowsPerDay="  Integer  "       trackApplicationName="[truefalse]"       trackPageUrl="[truefalse]"       counterGroup="  String  "       counterName="  String  ">         <pagesToCount>           <add path="  String  " />           <remove path="  String  " />           <clear/>       </pagesToCount>     </pageCounters> </siteCounters> 

The attributes are described in Table 13.18.

Table 13.18. siteCounters Attributes

Attribute	Description
enabled	Indicates whether or not the service is enabled. The default value is true .
defaultProvider	Indicates the provider to use if no explicit provider is named. The default value is AspNetAccessProvider . If no default provider is specified, the first provider in the collection is used as the default.
handlerPath	Indicates the URL used to handle click-throughs. The default is ~/counters.axd , which is an HttpHandler that intercepts page clicks and tracks the data.
handlerType	Defines the full name of the class that handles the site counter data. The shortened default is System.Web.Handlers.SiteCountersHandler full class details can be found in the configuration file.
rowsPerDay	Defines the granularity with which data is logged to the provider. The maximum value is 1440 (1 row per minute). The default value is 1 .

There are two supplied providers for site counters, AspNetAccessProvider and AspNetSqlProvider , both of which have the same provider-specific attributes, as shown in Table 13.19.

Table 13.19. Access and SQL Server Site Counters Attributes

Attribute	Description
name	The name of the provider.
type	The full class name of the provider.
connectionStringName	The name of the connection string, from the connectionStrings configuration elements, that defines the connection details for the tracking database. This property is specific to Access and SQL Server.
description	A description of the provider.
commitInterval	The interval, in seconds, between flushes of the in-memory counters to the database. The default is 90 .
commitTimeout	The time, in seconds, to wait before aborting the database command that writes the counters. The default is 60 .

The <pageCounters/> section allows configuration of how pages are tracked as part of the site counters service. The attributes are shown in Table 13.20.

Table 13.20. pageCounters Attributes

Attribute	Description
enabled	Indicates whether or not page tracking is enabled. This is ignored if site counters are disabled. The default value is false .
defaultProvider	Specifies the default provider to use for tracking pages.
rowsPerDay	Defines the granularity with which data is logged to the provider. The maximum value is 1440 (1 row per minute). The default value is 1 .
trackApplicationName	Indicates whether or not the application name is tracked with the site counter details. The default value is true .
trackPageUrl	Indicates whether or not the URL of the current page is tracked with the site counter details. The default value is true .
counterGroup	Defines the group name to use for tracked pages. The default is PageCounters .
counterName	Defines the counter name to use for tracked pages.

The <pagesToCount/> element contains a collection of page names, meaning that the add and remove elements do not behave like ordinary add and remove elements that have a key. For the add element, the default value is * , which indicates that all pages recursively are included. Under default conditions, therefore, the remove element indicates the pages to exclude.

Personalization

The <personalization/> section allows configuration of the Personalization service (see Listing 13.9).

Listing 13.9 personalization Configuration Syntax

 <personalization   enabled="[truefalse]"   defaultProvider="  String  ">   <providers>     <add name="  String  "       type="  String  "       [  providerSpecificSettings  ]       />     <remove name="  String  "       />     <clear />   </providers>   <profile>     <property name="  String  "       readOnly="[truefalse]"       serializeAs="[StringXmlBinaryProviderSpecific]"       provider="  String  "       defaultValue="  String  "       type="  String  "       allowAnonymous="[truefalse]"       />     <group name="  String  ">       <property />     </group>   </profile> </personalization> 

The attributes are described in Tables 13.21 and 13.22.

Table 13.21. personalization Attributes

Attribute	Description
enabled	A Boolean value indicating whether or not site maps are enabled. The default value is true .
defaultProvider	The name of the default provider. This should match one of the names supplied in the providers section. The default value is AspNetAccessProvider .

Table 13.22. personalization providers Attributes

Attribute	Description
name	The name of the site map provider.
type	A string containing the full .NET type of the provider.
providerSpecificSettings	The provider-specific settings.

The <profile/> section allows definition of custom types, such as a shopping cart, that can be stored with the Personalization details.

Table 13.23 shows the personalization profile attributes. Only the name attribute is requiredall others are optional.

Table 13.23. personalization profile Attributes

Attribute	Description
name	Specifies the name of the profile.
readOnly	Indicates whether or not the property is read-only. The default value is false .
serializeAs	Defines how the property is serialized. Can be one of the items from the SettingsSerializeAs enumeration (from System.Configuration.Settings ): String : Indicates the property is serialized as a string. Xml : Indicates the property is serialized as XML. Binary : Indicates the property is serialized in a binary format. ProviderSpecific : Indicates the property is serialized in a provider-specific way. The default value is ProviderSpecific .
provider	Defines the name of the property.
defaultValue	Defines the default value for the property.
type	Defines the type of the property.
allowAnonymous	Indicates whether or not values can be stored for anonymous users.

Page Personalization

The <pagePersonalization/> section details the Personalization providers available for individual pages (see Listing 13.10).

Listing 13.10 pagePersonalization Configuration Syntax

 <pagePersonalization   defaultProvider="String"   />   <providers>     <add name="String"       type="String"       [  providerSpecificSettings  ]       />     <remove name="String"       />     <clear />   </providers> </pagePersonalization> 

There is only one attribute for <pagePersonalization/> , which is defaultProvider . This defines the name of the default provider and defaults to AspNetAccessProvider . The attributes for the providers element are described in Table 13.24.

Table 13.24. pagePersonalization providers Attributes

Attribute	Description
name	Defines the name of the provider.
type	Defines the data type of the provider.

There are two supplied page Personalization providers, AspNetSqlProvider and AspNetAccessProvider , both of which have the same two provider-specific attributes, as described in Table 13.25.

Table 13.25. Access and SQL Server Page Providers Attributes

Attribute	Description
connectionStringName	Defines the name of the connection string, from the connectionStrings configuration section.
applicationName	Defines the name of the application to which the page provider has scope.

Protocols

The <protocols/> section defines the protocols available to the system and the protocol handlers that process them. Here's the syntax:

 <protocols>   <add     id="ISAPI"     processHandlerType="  String  "     appDomainHandlerType="  String  "     validate="[truefalse]"     /> </protocols> 

The attributes are described in Table 13.26.

Table 13.26. protocols Attributes

Attribute	Description
id	Specifies a unique protocol identifier.
processHandlerType	Specifies the full name of the type that handles the process. This attribute is optional; if unspecified, the protocol does not require a protocol handler.
appDomainHandlerType	Specifies the full name of the type of the application domain.
validate	Indicates whether or not processHandlerType and appDomainHandlerType should be validated as proper types. The default is true .

Role Manager

The <roleManager/> section allows configuration of roles for use in authorization (see Listing 13.11).

Listing 13.11 roleManager Configuration Syntax

 <roleManager   defaultProvider="  String  "   enabled="[truefalse]"   cacheRolesInCookies="[truefalse]"   cookieName="  String  "   cookieTimeout="  Integer  "   cookiePath="  String  "   cookieRequiresSSL="[truefalse]"   cookieSlidingExpiration="[truefalse]"   cookieProtection="[NoneValidationEncryptionAll]"   >   <providers>     <add name="  String  "       type="  String  "       [  providerSpecificSettings  ]       />     <remove name="  String  "       />     <clear />   </providers> </roleManager> 

The attributes for the <roleManager/> are described in Table 13.27.

Table 13.27. roleManager Attributes

Attribute	Description
defaultProvider	Indicates the name of the default role provider. The default value is AspNetAccessProvider .
enabled	Indicates whether or not the Role Manager is enabled. The default value is false .
cacheRolesInCookies	Indicates whether or not cookies are used to store role information. The default value is true .
cookieName	Specifies the name of the cookie. The default value is .ASPROLES .
cookieTimeout	Specifies the time, in minutes, before the cookie expires. This cannot be or less. The default value is 100000 .
cookiePath	Specifies the path, which is case-sensitive, used to write the cookie. Using '/' allows applications within the same domain to access the cookie. The default is '/' .
cookieRequiresSSL	Indicates whether or not the cookie requires an SSL connection in order to be written to the client. The default value is false .
cookieSlidingExpiration	Indicates whether the cookie timeout resets on each request (a value of true ) or expires at a fixed time (a value of false ). The default value is true .
cookieProtection	Specifies the protection scheme used to store the cookie. Can be one of the CookieProtection enumeration values (from System.Web.Security ): None : Indicates no protection is used. Validation : Indicates that the cookie is hashed and validated. Encryption : Indicates that the cookie is encrypted. All : Indicates that both validation and encryption are used. The default value is None .

Role Manager Providers

There are three supplied Role Manager providers:

• AspNetSqlProvider , which uses SQL Server to store and retrieve role information

• AspNetAccessProvider , which uses Access to store and retrieve role information

• WindowsToken , which retrieves role information from the Windows authenticated token

The SQL Server and Access providers have the following attributes:

• connectionStringName , which defines the name of the connection string in the connectionStrings configuration section

• applicationName , which defines the application to which the provider has scope

All three providers also have a description attribute.

Mail Servers

The <smtpMail/> section allows configuration of a mail server for use with the SMTP Mail class (see Listing 13.12).

Listing 13.12 smtpMail Configuration Syntax

 <smtpMail   serverName="  String  "   serverPort="  Integer  "   from="  String  ">   <fields>     <add name="  String  "       value="  String  "       typeName="  String  "       />     <remove name="  String  "       />     <clear />   </fields> </smtpMail> 

The attributes are described in Table 13.28.

Table 13.28. smtpMail Attributes

Attribute	Description
serverName	Defines the name of the SMTP server. The default value is localhost .
serverPort	Defines the port used to send mail. This must be a positive number; the default value is 25 .
from	Defines the from tag to use when sending mail.

Field Settings

The <fields/> section allows definition of custom fields for the SMTP mail server. The attributes are described in Table 13.29.

Table 13.29. smtpMail fields Attributes

Attribute	Description
name	Defines the name of the field.
value	Defines the value of the field.
typeName	Defines the data type of the field. The default value is String .

URL Mappings

The <urlMappings/> section allows configuration of URLs that will be rewritten, thus allowing the actual URL to be hidden. Here's the syntax:

 <urlMappings    enabled="[truefalse]">   <add     url="  String  "     mappedUrl="  String  "     />   <remove name="  String  "     /> </urlMappings> 

The attributes are detailed in Table 13.30. For removal, the url attribute must contain a relative URL starting with ~/ .

Table 13.30. urlMappings Attributes

Attribute	Description
enabled	Indicates whether or not the URL mappings service is enabled. The default is true .
url	Specifies the displayed URL. This must be a relative URL starting with ~/ .
mappedUrl	Specifies the actual URL. This must be a relative URL starting with ~/ .

Web Administration Tool

The Web Administration Tool (see Chapter 6) is configured with the <webSiteAdministrationTool/> section (see Listing 13.13).

Listing 13.13 webSiteAdministrationTool Configuration Syntax

 <webSiteAdministrationTool   defaultUrl="  String  "   physicalPath="  String  "   enabled="[truefalse]"   errorPage="  String  "   localOnly="[truefalse]"   >   <authorization>     <allow       [usersroles]="  String  "       applicationPath="  String  "       />     <deny       [usersroles]="  String  "       applicationPath="  String  "       />   </authorization>   <categories>     <category       title="  String  "       navigateUrl="  String  "       imageUrl="  String  "       selectedImageUrl="  String  "       />   </categories> </webSiteAdministrationTool> 

The attributes are described in Table 13.31.

Table 13.31. webSiteAdministrationTool Attributes

Attribute	Description
defaultUrl	Defines the URL of the Web Administration Tool, and is used by the HttpHandler to redirect requests to WebAdmin.axd to the correct URL. The default value is /aspnet_webadmin/default.aspx .
physicalPath	Defines the physical location of the Web Administration Tool. The default value is %SystemDrive%:\inetpub\ wwwroot \aspnet_webadmin\default.aspx .
enabled	Indicates whether or not the Web Administration Tool is enabled. The default value is true .
errorPage	Defines the page to use for displaying errors.
localOnly	Indicates whether or not the tool can be used only from the local machine (i.e., http://localhost ).

Authorization Settings

The <authorization/> section allows configuration of which users or roles are allowed access to which parts of the administration interface. The attributes are described in Table 13.32.

Table 13.32. authorization Attributes

Attribute	Description
users/roles	Specifies the collection of users or roles defining who is allowed or denied access to the Web Administration Tool.
applicationPath	Defines the application that the users or roles are allowed or not allowed to administer.

Categories

The <categories/> section defines the categories that appear on the main administration page. The attributes are shown in Table 13.33.

Table 13.33. categories Attributes

Attribute	Description
title	Defines the category title.
navigateUrl	Defines the relative or absolute URL that will be requested for this category.
imageUrl	Defines the relative or absolute URL that represents this category.
selectedImageUrl	Defines the relative or absolute URL that represents this category when it is selected.

The default categories are:

• Home

• Security

• Personalize

• Reports

• Data Access

For the Technology Preview, only the content for the Security tab is implemented; the other tabs are simply placeholders for future implementation.