Application Configuration Files





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

  • Build providers

  • 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

  • Expression builders

  • Hosting

  • Image generation

  • HTTP cookies

  • Membership

  • Site maps

  • Site counters

  • Personalization Profile

  • Protocol bindings

  • Role Manager

  • Mail servers

  • URL mappings

  • Web Parts

  • Web Site Administration Tool

  • Protected data

  • Health monitoring

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 here:






<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 here:






<compilation

  urlLinePragmas="[true|false]"

  >

    <codeSubDirectories>

      <add directoryName="String" />

    </codeSubDirectories>

  </compilation>


A new Boolean attribute on the main compilation section, urlLinePragmas, 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, within the <compilation/> section, identifies which files are part of the dynamic compilation process. This section has the following syntax:






<buildProviders>

  <add

    extension="String"

    appliesTo="String"

    type="String" />

</buildProviders>


The attributes are described in Figure.

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.


The <buildProviders/> 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 (under the <system.net/> section) defines how the System.Net classes access the Internet and has been enhanced to include the following settings:






<defaultProxy

  scriptDownloadInterval="Integer"

  scriptDownloadTimeout="Integer"

  useDefaultCredentialsForScriptDownload="[true|false]"

  />


The attributes are described in Figure.

defaultProxy Attributes

Attribute

Description

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.

useDefaultCredentialsForScriptDownload

Indicates whether or not default credentials are used when accessing the configuration script.


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.

  • Profile provides support for Personalization.

  • PageCountersModule provides support for the page counters.

  • SqlBatchModule provides support for batch SQL commands.

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 new attributes shown in Listing 13.1.

httpRuntime Syntax

<httpRuntime

  enable="[true|false]"

  requestLengthDiskThreshold="Integer"

  requireRootedSaveAsPath="[true|false]"

  waitChangeNotification="Integer"

  maxWaitChangeNotification="Integer"

  compilationTempDirectory="String"

  requestPriority="[Normal|High|Critical]"

  />


The attributes are described in Figure on the next page.

httpRuntime Attributes

Attribute

Description

enable

Indicates whether or not the current application domain (and those below it) is enabled. The default value is true.

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.

waitChangeNotification

Indicates the time in seconds to wait for another file change notification before restarting the application domain.

maxWaitChangeNotification

Indicates the maximum time in seconds to wait from the first file change notification before restarting the application domain.

compilationTempDirectory

Indicates the directory for temporary files used during compilation.

requestPriority

Indicates the request priority.


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 requestLengthDiskThreshold and requireRootedSaveAsPath attributes are for file uploads. They define the maximum size of uploaded files and whether the upload path where files are saved must be rooted, respectively.

HTTP Handlers

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

  • WebAdmin.axd, for the Web Site 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

  • WebPartExport.axd, for exporting settings of Web Parts to an XML file

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

  • .asix

  • .master

  • .skin

  • .browser

  • .mdb

  • .ldb

  • .sitemap

  • .mdw

Globalization

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






<globalization

  responseHeaderEncoding="String"

  enableClientBasedCulture="[true|false]"

  />


The responseHeaderEncoding allows the encoding to be set for response headers. The default is utf-8.

The enableClientBasedCulture 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, a new subelement allows automatic addition of namespace references to each page (see Listing 13.2).

pages Configuration Syntax

<pages

  compilationMode="[Auto|Never|Always]"

  maxPageStateFieldLength="Integer"

  masterPageFile="String"

  theme="String"

  stylesheetTheme="String"

  >

  <namespaces>

    <add namespace="String" />

  </namespaces>

</pages>


The attributes are described in Figure. Both the masterPageFile and theme attributes can be overridden at the page level.

pages Attributes

Attribute

Description

compilationMode

Indicates the mode of compilation. Can be Always, Auto, or Never. The default is Always.

maxPageStateFieldLength

Indicates the maximum length of the field used for ViewState. If set, the VIEWSTATE field is split into multiple fields (VIEWSTATE, VIEWSTATE1, VIEWSTATE2, and so on) so that each field does not exceed the maximum size as specified by this setting.

masterPageFile

Defines the site-wide master page. This allows a master page to be applied to all pages without adding the masterPageFile 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.

stylesheetTheme

Defines the site-wide stylesheet theme. This allows a stylesheet theme to be applied to all pages without adding the StylesheetTheme 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.Profile

  • System.Web.UI

  • System.Web.UI.Imaging

  • System.Web.UI.WebControls

  • System.Web.UI.WebControls.WebParts

  • System.Web.UI.HtmlControls

In addition to globally defining namespaces, tag controls can also be defined through the use of a controls subelement, as shown in this example:






<controls>

  <add

    tagPrefix="asp"

    namespace="System.Web.UI.WebControls.WebParts"

    assembly="85" />

</controls>


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="[Off|InProc|StateServer|SQLServer|Custom]"

  sqlCommandTimeout="Integer"

  customProvider="String"

  cookieName="String"

  allowCustomSqlDatabase="[true|false]"

  >

  <providers>

    <clear />

    <add

      Name="String"

      Type="String"

      [providerSpecificConfiguration] />

  </providers>

</sessionState>


The new attributes are described in Figure.

sessionState Attributes

Attribute

Description

mode

Indicates how session state is being managed. This has been enhanced to allow the new Custom value, which indicates that session state is stored in a custom manner.

sqlCommandTimeout

Indicates, in seconds, the timeout for a SQL command when the mode is SQLServer. The default value is 30.

customProvider

Indicates the name of the provider when the mode is Custom. The name attribute should match one of the provider names declared in the <Providers/> section.

cookieName

Defines the default cookie name used to store the session ID.

allowCustomSqlDatabase

Indicates whether or not a custom database name can be specified in the Initial Catalog attribute of the SQL Server connection string.


The addition of the <providers/> element brings session state handling inline with the standard provider model, allowing you to define custom providers.

In the Technology Preview release there was no <providers/> section. Instead only a single custom provider could be specified through the use of the customType attribute.


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 the session state could 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 <webRequestModules/> section 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 in the next several pages.

Anonymous Identification

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

anonymousIdentification Configuration Syntax

<anonymousIdentification

  enabled="[true|false]"

  cookieName="String"

  cookieTimeout="Integer"

  cookiePath="String"

  cookieRequireSSL="[true|false]"

  cookieSlidingExpiration="[true|false]"

  cookieProtection="[None|Validation|Encryption|All]"

  cookieless="[UseCookies|UseUri|AutoDetect|UseDeviceProfile]"

  />


The attributes are described in Figure.

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 0 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 '/'.

cookieRequireSSL

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:

  • UseCookies: Forces the authentication ticket to be stored in the cookie (same as ASP.NET 1.x behavior).

  • UseUri: Forces the authentication ticket to be stored in the URL.

  • 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.4).

system.codedom Configuration Syntax

<system.codedom>

  <compilers>

    <compiler

      language="String"

      extensions="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.






<connectionStrings>

  <add name="String"

    connectionString="String"

    providerName="String"

  />

  <remove name="String" />

  <clear />

</connectionStrings>


The attributes are described in Figure.

connectionStrings Attributes

Attribute

Description

name

The name of the connection string.

connectionString

The full connection details. No validity checking is performed.

providerName

The name of the data provider, for example, "System.Data.SqlClient".


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").ConnectionString



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.5).

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 Figure.

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—already an area of ASP.NET that led to performance enhancements—has been greatly improved in ASP.NET 2.0, with new features and configuration of existing features. All of this is exposed underneath the <caching/> section, which has no attributes itself but contains the following subsections:

  • <cache/>, for the cache API

  • <outputCache/>, for disk caching

  • <outputCacheSettings/>, to define cache profiles that can be used by pages

  • <sqlCacheDependency/>, to configure SQL Server–based cache dependencies

The syntax for the <cache/> element is shown in Listing 13.6.

cache Configuration Syntax

<cache

  cacheAPIEnabled="[true|false]"

  disableMemoryCollection="[true|false]"

  disableExpiration="[true|false]"

  />


The attributes for <cache/> are described in Figure.

cache Attributes

Attribute

Description

cacheAPIEnabled

Indicates whether or not the Cache API is enabled. If disabled, calls to the Cache API will have no effect. This does not affect ASP.NET internal usage of the Cache. The default value is true.

disableMemoryCollection

Indicates whether or not the cache memory collection is enabled. The default value is false.

disableExpiration

Indicates whether or not the expiration of items from the cache is enabled. The default value is true.


The syntax for the <outputCache/> element is shown in Listing 13.7.

outputCache and diskCache Configuration Syntax

<outputCache enabled="[true|false]">

  <diskCache

    enabled="[true|false]"

    path="String"

    maxDiskPercentTotal="Integer"

    maxSizePerApp="Integer"

    />

</outputCache>


The attributes for <outputCache/> and <diskCache/> are described in Figure.

outputCache and diskCache Attributes

Attribute

Description

enabled

If used on the outputCache element, indicates whether or not the output cache is enabled. If used on the diskCache element, indicates whether or not disk-based persistent caching is enabled. The default in both cases is true.

path

Defines the location for disk-based persistent cache entries.

maxDiskPercentTotal

Indicates the maximum size, as a percentage of the disk size, of the disk cache. The default is 10.

maxSizePerApp

Indicates the maximum size, in megabytes, of the cache per application. The default is 5.


The <outputCacheSettings/> section has no attributes but has two subsections to allow configuration of the cache profiles (<outputCacheProfiles/>) and fragment cache profiles (<fragmentCacheProfiles/>). The syntax for these is the same, as shown in Listing 13.8.

outputCacheProfiles and fragmentCacheProfiles Configuration Syntax

<outputCacheProfiles>

  <clear />

  <add

    name="String"

    enabled="[true|false]"

    diskCacheable="[true|false]"

    duration="Integer"

    location="String"

    shared="[true|false]"

    sqlDependency="String"

    varyByControl="String"

    varyByCustom="String"

    varyByHeader="String"

    varyByParam="String"

    noStore="[true|false]"

    />

</outputCacheProfiles>


The attributes for cache profiles are described in Figure.

outputCacheProfiles and fragmentCacheProfiles Attributes

Attribute

Description

name

Indicates the name of the profile, which can be referenced by the CacheProfile attribute of the OutputCache page directive.

enabled

Indicates whether or not caching for the profile is enabled.

diskCacheable

Indicates whether or not the profile caches to disk.

duration

Defines how long, in seconds, to cache the data.

location

Defines the location where the data is cached along the server/proxy/client path. The values can be

  • Any, allowing the output cache to be located anywhere

  • Client, to specify the output cache is located on the client

  • Downstream, to specify the cache can be stored in any HTTP 1.1 cache device

  • None, to disable the output cache

  • Server, to specify the cache is located on the server where the request was processed

  • ServerAndClient, to specify the cache can be stored only on the processing server or the requesting client

shared

Applies only to user controls, and indicates whether a cached version of the control can be shared between pages. Sharing of cached user controls is not supported in beta release 1.

sqlDependency

Defines a SQL dependency string.

varyByControl

Defines the comma-separated list of controls to vary by.

varyByCustom

Defines the comma-separated list of custom strings to vary by.

varyByHeader

Defines the comma-separated list of headers to vary by.

varyByParam

Defines the comma-separated list of parameters to vary by.

noStore

Indicates whether or not a Cache-Control:no-store header is sent, to prevent caching on secondary cache servers.


The <sqlCacheDependency/> section defines dependencies on SQL Server tables. The syntax is shown in Listing 13.9.

cache Configuration Syntax

<sqlCacheDependency

  enabled="[true|false]"

  pollTime="Integer"

  >

  <databases>

    <add

      name="String"

      connectionStringName="String"

      pollTime="Integer"

      />

    <remove

      name="String"

      />

  </databases>

</sqlCacheDependency>


The attributes for <sqlCacheDependency/> and <databases/> are described in Figure and 13.13, respectively.

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.


databases Attributes

Attribute

Description

name

Indicates the name of the database.

connectionStringName

Indicates the name of the connection string from the <connectionStrings/> configuration section.

pollTime

Defines the time, in milliseconds, between polls. If not specified, the pollTime from the parent element is used.


For more details on caching, please see Chapter 12. In the Technology Preview release only database caching was supported, under the <cache/> element.


Expression Builders

The <expressionBuilders/> section identifies inline expressions and the class used to evaluate them. The syntax for this section is shown here:






<expressionBuilders>

  <add

    expressionPrefix="String"

    type="String" />

</expressionBuilders>


The three configured expression builders are Resources, Connection Strings, and AppSettings, allowing dynamic binding that uses the following syntax:
















<%$ ConnectionStrings: pubs %>


Hosting

The <hostingEnvironment/> section allows configuration of timeouts for hosted environments. Listing 13.10 shows the syntax.

hostingEnvironment Configuration Syntax

<hostingEnvironment

  idleTimeout="Integer"

  shutdownTimeout="Integer"

  />


The attributes are described in Figure.

hostingEnvironment Attributes

Attribute

Description

idleTimeout

Indicates the time, in minutes, to unload the application.

shutdownTimeout

Indicates the time, in minutes, given for graceful shutdown of the application.


Image Generation

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






<imageGeneration

  storageType="[Cache|Disk]"

  storagePath="String"

  storageExpiration="Integer"

  customErrorImageUrl="String"

  />


The attributes are described in Figure.

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:

  • Cache: Indicates storage in the cache.

  • Disk: Indicates storage on disk.

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.

customErrorImageUrl

The URL to an image to display when an unhandled exception is thrown.


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="[true|false]"

  requireSSL="[true|false]"

  domain="String"

  />


The attributes are described in Figure.

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.11).

membership Configuration Syntax

<membership

  defaultProvider="String"

  userIsOnlineTimeWindow="Integer">

  <providers>

    <add name="String"

      type="String"

      [providerSpecificSettings]

      />

    <remove name="String"

     />

    <clear />

  </providers>

</membership>


The membership and providers attributes are described in Figure and 13.18, respectively.

membership Attributes

Attribute

Description

defaultProvider

The name of the default provider. There is no default value.

userIsOnlineTimeWindow

The time, in minutes, since the last activity when the user was deemed to be online. The default value is 15.


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="[true|false]"

enablePasswordReset="[true|false]"

requiresQuestionAndAnswer="[true|false]"

applicationName="String"

requiresUniqueEmail="[true|false]"

passwordFormat="[Clear|Hashed|Encrypted]"

description="String"


The attributes are described in Figure.

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.

requiresQuestionAndAnswer

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. Values 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.12).

sitemap Configuration Syntax

<siteMap

    defaultProvider="String"

    enabled="[true|false]">

  <providers>

    <add

      name="String"

      type="String"

      securitytrimmingEnabled="[true|false]"

      [providerSpecificSettings]

      />

    <remove name="String"

      />

    <clear />

  </providers>

</siteMap>


The siteMap and siteMap providers attributes are described in Figure and 13.21, respectively.

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.


siteMap providers Attributes

Attribute

Description

name

The name of the site map provider.

type

A string containing the full .NET type of the provider.

securityTrimmingEnabled

Indicates whether or not security trimming is enabled, allowing the nodes to be filtered by selected roles. The default value is false.

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.13).

siteCounters Configuration Syntax

<siteCounters

  enabled="[true|false]"

  defaultProvider="String"

  handlerPath="String"

  handlerType="String"

  rowsPerDay="Integer"

  >

    <providers>

      <add

        name="String"

        type="String"

        [providerSpecificSettings]

        />

      <remove

        name="String" />

      <clear/>

    </providers>



    <pageCounters

      enabled="[true|false]"

      defaultProvider="String"

      rowsPerDay="Integer"

      trackApplicationName="[true|false]"

      trackPageUrl="[true|false]"

      counterGroup="String"

      counterName="String">



        <pagesToCount>

          <add path="String" />

          <remove path="String" />

          <clear/>

      </pagesToCount>

    </pageCounters>

</siteCounters>


The attributes are described in Figure.

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.


The two supplied providers for site counters, AspNetAccessProvider and AspNetSqlProvider, both have the same provider-specific attributes, as shown in Figure.

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 Figure.

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 for the path attribute is *, which indicates that all pages recursively are included. Under default conditions, therefore, the remove element indicates the pages to exclude.

Personalization Profile

The <profile/> section allows configuration of the Personalization Profile service (see Listing 13.14).

profile Configuration Syntax

<profile

  enabled="[true|false]"

  defaultProvider="String">

  <providers>

    <add name="String"

      type="String"

      [providerSpecificSettings]

      />

    <remove name="String"

      />

    <clear />



  <properties>

    <add

      name="String"

      readOnly="[true|false]"

      serializeAs="[String|Xml|Binary|ProviderSpecific]"

      provider="String"

      defaultValue="String"

      type="String"

      allowAnonymous="[true|false]"

      />

    <remove

      name="String"

      />

    <clear />

    <group name="String">

      <add

        name="String"

        readOnly="[true|false]"

        serializeAs="[String|Xml|Binary|ProviderSpecific]"

        provider="String"

        defaultValue="String"

        type="String"

        allowAnonymous="[true|false]"

        />

      <remove

        name="String"

        />

    </group>

  </properties>

</profile>


The profile and profile providers attributes are described in Figure and 13.26, respectively.

profile Attributes

Attribute

Description

enabled

A Boolean value indicating whether or not the profile is 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.


profile providers Attributes

Attribute

Description

name

The name of the profile provider.

type

A string containing the full .NET type of the provider.

providerSpecificSettings

The provider-specific settings.


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

Figure shows the attributes of an individual property, as configured by the <add/> section. Only the name attribute is required—all others are optional.

Individual Profile Property 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.


The <group/> section allows profile properties to be grouped into logical units. Each group is given a name, and within that group you can add properties, taking the same attributes as those in the <properties/> section.

Protocol Bindings

The <httpProtocolBindings/> section allows file types to be mapped to different HTTP pipelines in IIS. This will be used by Indigo to map the .svc file type to the appropriate pipeline. Listing 13.15 shows the syntax.

httpProtocolBindings Configuration Syntax

<httpProtocolBindings defaultType="String">

  <add

    extension="String"

    type="String"

    validate="[true|false]"

  <clear />

</httpProtocolBindings>


The defaultType identifies the default type to be used and defaults to System.Web.Hosting.AspNetHttpWorkerRequestHandler. The attributes for added types (which map to the HttpProtocolBinding class) are shown in Figure.

httpProtocolBindings Attributes

Attribute

Description

extension

Indicates the file extension to be mapped to the handler.

type

Defines the type used to handle the protocol.

validate

Indicates whether or not the type is validated.


Role Manager

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

roleManager Configuration Syntax

<roleManager

  defaultProvider="String"

  enabled="[true|false]"

  cacheRolesInCookie="[true|false]"

  cookieName="String"

  cookieTimeout="Integer"

  cookiePath="String"

  cookieRequireSSL="[true|false]"

  cookieSlidingExpiration="[true|false]"

  cookieProtection="[None|Validation|Encryption|All]"

  >

  <providers>

    <add name="String"

      type="String"

      [providerSpecificSettings]

      />

    <remove name="String"

      />

    <clear />

  </providers>

</roleManager>


The attributes for the <roleManager/> section are described in Figure.

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.

cacheRolesInCookie

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 0 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 '/'.

cookieRequireSSL

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 four 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

  • AuthorizationStoreRoleProvider, which uses the Authorization Manager

  • 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

The Authorization Manager provider has 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

  • scopeName, which indicates the scope (role information) within the application to which the authorization applies

All four providers also have description and type attributes.

Mail Servers

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

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 Figure.

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 Figure.

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="[true|false]">

  <add

    url="String"

    mappedUrl="String"

    />

  <remove name="String"

    />

</urlMappings>


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

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 Parts

The <webParts/> section allows for configuration of Web Part personalization and data transformation. The configuration syntax is shown in Listing 13.18.

webParts Configuration Syntax

<webParts>

  <personalization defaultProvider="String">

    <providers>

      <add

        name="String"

        type="String"

        />

      <remove name="String" />

      <clear />

    </providers>



    <authorization />



  </personalization>



  <transformers>

    <add

      name="String"

      type="String"

      />

    <remove name="String" />

    <clear />

  </transformers>

</webParts>


The <providers/> section follows the standard provider pattern, allowing personalization providers to be added or removed. The <authorization/> section follows the same format as for setting application authorization.

The <transformers/> section allows definition of data transformers, which convert data exposed by one Web Part into data accepted by another. This follows the standard provider pattern, allowing declaration of a transformer by its name and data type. There are three default transformers to convert Web Parts that implement the IRow interface into other forms:

  • RowToFieldTransformer, to convert a row into a field

  • RowToFilterTransformer, to convert a row into a filter

  • RowToParameterTransformer, to convert a row into parameters

Web Parts are covered in Chapter 8.

Web Site Administration Tool

The Web Site Administration Tool is configured with the <webSiteAdministrationTool/> section (see Listing 13.19).

webSiteAdministrationTool Configuration Syntax

<webSiteAdministrationTool

  defaultUrl="String"

  enabled="[true|false]"

  errorPage="String"

  localOnly="[true|false]"

  requireSSL="[true|false]"

  >

  <authorization>

    <allow

      [users|roles]="String"

      applicationPath="String"

      />

    <deny

      [users|roles]="String"

      applicationPath="String"

      />

  </authorization>

  <categories>

    <category

      title="String"

      navigateUrl="String"

      />

  </categories>

</webSiteAdministrationTool>


The attributes are described in Figure.

webSiteAdministrationTool Attributes

Attribute

Description

defaultUrl

Defines the URL of the Web Site 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.

enabled

Indicates whether or not the Web Site 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).

requireSSL

Indicates whether or not the tool requires a secure channel.


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 Figure.

authorization Attributes

Attribute

Description

users/roles

Specifies the collection of users or roles defining who is allowed or denied access to the Web Site Administration Tool.

applicationPath

Defines the application that the users or roles are allowed or not allowed to administer.


The default value for the <authorization/> section is to allow all users from all application paths.

Categories

The <categories/> section defines the categories that appear on the main administration page, under which there are <category/> elements. Figure shows the attributes for these elements.

category Attributes

Attribute

Description

title

Defines the category title.

navigateUrl

Defines the relative or absolute URL that will be requested for this category.


The default categories are:

  • Home

  • Security

  • Profile

  • Application

  • Provider

Use of the tool is covered later in this chapter under the Web Site Administration Tool section.

Protected Data

Encryption of items within the configuration file (web.config) is now supported by the <protectedData/> section, the syntax of which is shown in Listing 13.20.

protectedData Configuration Syntax

<protectedData defaultProvider="String">

  <providers>

    <add

      name="String"

      type="String"

      description="String"

      [providerSpecificConfiguration]

      />

    </providers>

    <protectedDataSections>

      <add

        name="String"

        Provider="String"

        />

    </protectedDataSections>

</protectedData>


This follows the standard provider pattern, and two providers are configured by default: RSAProtectedConfigurationProvider (the default) and DataProtectionConfigurationProvider, both implemented in System.Configuration.

The properties for the RSAProtectedConfigurationProvider are detailed in Figure.

RSAProtectedConfigurationProvider Attributes

Attribute

Description

cspProviderName

Specifies the name of the configuration section provider.

keyContainerName

Specifies the name of the key container used to store the key. Valid names are determined by the configuration section provider.

keyName

Specifies the name of the key.

RSAPublicKey

Specifies the RSA public key that corresponds to the key container.

useMachineContainer

Specifies whether or not a machine key container is used. The default value is true.

useOAEP

Specifies whether or not to use the optimal asymmetric encryption padding (OAEP) algorithm when writing the configuration. The default value is false.


The properties for the DataProtectionConfigurationProvider are detailed in Figure.

DataProtectionConfigurationProvider Attributes

Attribute

Description

doNotShowUI

Indicates whether or not to suppress the access user interface if the encryption is called from the client configuration system. The default value is true.

keyEntropy

Specifies the optional entropy for encryption and decryption.

keyName

Specifies the name of the key.

useMachineProtection

Indicates whether to use the per-machine mode of the API.


Sections within the configuration file are defined by use of the <protectedDataSections/> element, like so:






<protectedDataSections>

  <add name="connectionStrings"

       provider="RSAProtectedConfurationProvider" />

  <add name="appSettings"

       provider="RSAProtectedConfurationProvider" />

  <add name="system.web/identity"

       provider="RSAProtectedConfurationProvider" />

</protectedDataSections>


The section name should be in XPath syntax.

Sections Not Supported by Encryption

Several sections cannot be encrypted because they are not handled by section handlers, or they are consumed by the CLR by native code or XML parsers. These sections are listed here:

  • <processModel/>

  • <runtime/>

  • <mscorlib/>

  • <startup/>

  • <system.runtime.remoting/>

  • <protectedData/>

  • <satelliteAssemblies/>

  • <cryptographySettings/>

  • <cryptoNameMapping/>

  • <cryptoClasses/>

Section Encryption Tool

The aspnet_regiis.exe tool, which has been enhanced with the switches shown in Figure, is used to manage protected sections of the configuration file. A separate tool for this may be provided in the future.

Encryption Tool Switches

Switch

Operation

-pe

Encrypt.

-pd

Decrypt.

-pc

Create key.

-pz

Delete key.

-pi

Import key.

-px

Export key.

-pa

Add ACE.

-pr

Remove ACE.

-csp

Use this configuration section provider for the operation.

-pku

Use the keystore for the current user. By default the machine store is used.

-prov

Specify the provider to use for the operation.

-app

Treat the following virtual path as an application file. By default machine.config is used.


Figure shows the syntax for using these switches.

Syntax for Encryption Tool Switches

Action

Switches

Encryption

-pe configurationXPath [-prov provider] [-app virtualPath]

Decryption

-pd configurationXPath [-app virtualPath]

Create key

-pc ContainerName [-csp csp] [-pku] [-exp] [-size sizeSpecifier]

Delete key

-pz ContainerName [-csp csp] -pkm|-pku

Import key

-pi ContainerName InputFile [-csp] [-pku] [-exp]

Export key

-px ContainerName ExportFile [-csp] [-pku] [-pri]

Add ACE

-pa ContainerName Account [-csp] [-pku] [-full]

Remove ACE

-pr ContainerName Account [-csp] [-pku]


For example, to encrypt a section you first create a public key:






aspnet_regiis -pc MySecretKeys -pku -exp -size 1024


The encryption can then be done by using this code:






aspnet_regiis -pe connectionStrings -app MyApplicationName


In shared environments it may be necessary to export keys so that a centrally stored encrypted configuration file (e.g., one stored in a source code control system) can be checked out and used by developers. The keys can be exported from the server like so:






aspnet_regiis -px MySecretKeys myKeys.xml –pri


The developer can then import them into the local Web Server:






aspnet_regiis –pi MySecretKeys myKeys.xml


Encryption of configuration sections was not supported in the Technology Preview release.


Health Monitoring

The <healthMonitoring/> section allows configuration of the ASP.NET Windows monitoring data, allowing it to be written to a variety of data stores such as SQL Server or Windows Management Instrumentation (WMI). This data can be consumed by products such as HealthMon. Listing 13.21 shows the syntax for this section.

healthMonitoring Configuration Syntax

<healthMonitoring

  enabled="[true|false]"

  heartBeatInterval="Integer">



  <bufferModes>

    <add name="String"

      maxBufferSize="Integer"

      maxFlushSize="Integer"

      urgentFlushThreshold="Integer"

      regularFlushInterval="[Infinite|Integer]"

      urgentFlushInterval="TimeSpan"

      maxBufferThreads="Integer"

      />

  </bufferModes>



  <providers>

    <add

      name="String"

      type="String"

      [providerSpecificProperties]

      />

  <clear />

  </providers>



  <eventMappings>

    <add

      name="String"

      type="String"

      startEventCode="Integer"

      endEventCode="Integer"

      />

    <clear />

  </eventMappings>



  <profiles>

    <add name="String"

      minInstances="Integer"

      maxLimit="[Infinite|Integer]"

      minInterval="TimeSpan"

      custom="String"

      />

    <clear />

  </profiles>



  <rules>

    <add name="String"

      eventName="String"

      provider="String"

      profile="String"

      minInterval="TimeSpan"

      minInstances="Integer"

      maxLimit="[Infinite|Integer]"

      custom="String"

      />

    <clear />

    <remove

      name="String" />

  </rules>



</healthMonitoring>


For the root <healthMonitoring/> element the attributes allow health monitoring to be enabled or disabled and the heartBeatInterval set, which specifies how often, in seconds, the WebHeartBeatEvent is raised. The default is 0, which means the event is never raised.

Buffer Modes

Buffer modes define the number of events that are buffered and how often the buffer is flushed. The properties for the <bufferModes/> section are shown in Figure.

bufferModes Attributes

Attribute

Description

name

The name of the buffer mode setting.

maxBufferSize

The maximum number of events that can be buffered at one time.

maxFlushSize

The number of events flushed in a single flush.

urgentFlushThreshold

The number of events accumulated in the buffer before it is flushed.

regularFlushInterval

The time between attempted buffer flushes.

urgentFlushInterval

The minimum time that must pass between flushes.

maxBufferThreads

The maximum number of threads used for buffering.


Four buffer modes are configured by default (Critical Notification, Notification, Analysis, and Logging); their properties are shown in Figure.

Configured Buffer Modes

Attribute

Value

Value

Value

Value

name

Critical Notification

Notification

Analysis

Logging

maxBufferSize

100

300

1000

1000

maxFlushSize

20

20

100

200

urgentFlushThreshold

1

1

100

800

regularFlushInterval

Infinite

Infinite

00:05:00

00:30:00

urgentFlushInterval

00:01:00

00:01:00

00:01:00

00:05:00

maxBufferThreads

1

1

1

1


Providers

The health monitoring <providers/> section defines the providers used to write WMI events. There are only two mandatory properties, name and type, which follow the standard conventions for providers, giving the name and full type of the provider class. Each provider can then implement specific properties as required. Three providers are configured by default:

  • EventLogProvider, which writes events to the Event Log

  • SqlWebEventProvider, which writes events to SQL Server

  • WmiWebEventProvider, which writes to the WMI event sink

Only the SQL Server provider has additional attributes, which are described in Figure.

SqlWebEventProvider Attributes

Attribute

Description

connectionStringName

The name of the connection string. The default value is LocalSqlServer.

maxEventDetailsLength

The maximum length for event details. The default is 1073741823.

buffer

Indicates whether or not events are buffered. The default value is false.

bufferMode

The name (as shown in Figure) of the buffer mode to use if buffering is enabled. The default value is Notification.


Event Mappings

The <eventMappings/> section maps event codes to event classes. The attributes are shown in Figure.

eventMappings Attributes

Attribute

Description

name

The name of the event class.

type

The type of the event class.

startEventCode

The starting event code range. The default is 0.

endEventCode

The ending event code range. The default is the maximum size for an integer (Int32.MaxValue).


By default the following events are mapped, all using the default values for the event codes:

  • System.Web.Management.WebBaseEvent

  • System.Web.Management.WebHeartBeatEvent

  • System.Web.Management.WebApplicationLifetimeEvent

  • System.Web.Management.WebRequestEvent

  • System.Web.Management.WebBaseErrorEvent

  • System.Web.Management.WebErrorEvent

  • System.Web.Management.WebRequestErrorEvent

  • System.Web.Management.WebAuditEvent

  • System.Web.Management.WebFailureAuditEvent

  • System.Web.Management.WebSuccessAuditEvent

Profiles

The <profiles/> section allows profiles to be defined for health events. The attributes are shown in Figure.

profiles Attributes

Attribute

Description

name

The name of the profile.

minInstances

The minimum number of occurrences of the event before it is fired. The default value is 1.

maxLimit

The maximum number of occurrences of the event, after which it stops being fired. The default value is Infinite.

minInterval

The minimum time between two events of the same type being fired. The default value is 0.

custom

The full type of a class that implements IWebEventCustomEvaluator.


Two profiles, named Default and Critical, are configured by default, both with minInstances set to 1 and maxLimit set to Infinite. For Default the minInterval is 1 minute (00:01:00), and for Critical it is 0 (00:00:00).

Rules

The <rules/> section defines the mappings between event types, providers, and associated profiles. They dictate which event is sent to which provider and which throttling parameters are applied. Figure shows the attributes.

rules Attributes

Attribute

Description

name

The name of the rule.

eventName

The name of the event type, as specified in the <eventMappings/> section.

provider

The name of the provider.

profile

The name of the profile for the event type, as specified in the <profiles/> section.


In addition, the <rules/> section supports the same attributes supported by the <profiles/> section (shown in Figure), allowing those profile attributes to be overridden for rules.

Two rules (All Errors Default and Failure Audits Default) are configured by default, as shown in Figure.

Default Rules

Attribute

Value

Value

name

All Errors Default

Failure Audits Default

eventName

All Errors

Failure Audits

provider

EventLogProvider

EventLogProvider

profile

Default

Default

minInterval

00:01:00

00:01:00


Health monitoring was not supported in the Technology Preview release.



     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows