ASP.NET Session State Provider Configuration Settings in Azure In-Role Cache

  • Article

Important

Microsoft recommends all new developments use Azure Redis Cache. For current documentation and guidance on choosing an Azure Cache offering, see Which Azure Cache offering is right for me?

This topic covers the configuration settings for the Azure session state provider for ASP.NET. These settings are specified in the providers section of the sessionState element in the web.config file.

Session State Configuration Settings

Attribute Description

name (required)

The “friendly” name of the provider used by the sessionState element to reference the provider.

type (required)

The .NET Framework type string for the provider. See the note below on the required value.

cacheName (required)

The name of the Azure cache. This must be set to “default”.

dataCacheClientName (optional)

The name of the dataCacheClient section to use from the dataCacheClients configuration section. This attribute is only required if multiple dataCacheClient sections are specified in the web.config file. By default, the provider will use the dataCacheClient section named “default”.

applicationName (optional)

A string value used by the provider when creating cache keys for storing output cache data. The default is an empty string. When this attribute is not set the provider uses the value of HttpRuntime.AppDomainAppId as part of the cache keys it uses internally. Unlike the session state feature, you do not want to share output cache data across different ASP.NET applications (for example, /contoso and /AdventureWorks cannot share output cache data). Instead ensure that different physical instances of the same application all have access to the same output cache data. There are two different ways to accomplish this:

  • If the applicationName provider attribute is not explicitly set, then HttpRuntime.AppDomainAppId is used internally by the provider when constructing cache keys. This means each physical instance of the same application (i.e. each web server hosting the /contoso application) needs to be installed in IIS with the exact same metabase path. See https://support.microsoft.com/kb/325056for an explanation of how metabase paths are used with the SQL Server and out-of-process session state providers. Although session state is a different feature, the same issue exists with keeping metabase paths in sync. This applies to output caching when the applicationName attribute has not been set in the web.config file.

  • An easier approach is for each instance of the same ASP.NET application (for example, on each web server hosting the /contoso application) to use the same applicationName attribute in the web.config file. This allows different physical instances of the same application to read and write the same output cache data. In this case the provider does not use AppDomainAppId when constructing cache keys and hence there is no risk of mismatched metabase paths.

useBlobMode (optional)

A boolean value that specifies whether to load and store session state data as a single serialized blob. This attribute must be set to true in this release, which is the default. Using a value of false is unsupported.

nonInlinedAdditionalLifetime (unsupported)

This attribute is unsupported in this release.

retryInterval (optional)

A timespan for the length of time to wait between retry attempts if an error occurs when communicating with the cache. The string format to use for this value is "HH:MM:SS". By default the provider will sleep for one second.

retryCount (optional)

An integer value that tells the provider the number of retry attempts in the event of a communications failure with the cache. Note that not all operations are able to be retried. The default value is three retry attempts. The provider sleeps for the configured retryInterval time between each retry attempt.

inlinedKeys (unsupported)

This attribute is unsupported in this release.

maxInlinedStringLength (unsupported)

This attribute is unsupported in this release.

Note

The type attribute should be set to “Microsoft.Web.DistributedCache.DistributedCacheOutputCacheProvider, Microsoft.Web.DistributedCache”.

Example

<configuration>
  <configSections>
    <section name="dataCacheClients" 
          type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core"
          allowLocation="true" allowDefinition="Everywhere" />
    <section name="cacheDiagnostics"
          type="Microsoft.ApplicationServer.Caching.AzureCommon.DiagnosticsConfigurationSection, Microsoft.ApplicationServer.Caching.AzureCommon"
          allowLocation="true" allowDefinition="Everywhere" />
  </configSections>
  <system.web>
    <!-- Azure Caching session state provider -->
    <sessionState mode="Custom" customProvider="AFCacheSessionStateProvider">
      <providers>
        <add name="AFCacheSessionStateProvider" 
          type="Microsoft.Web.DistributedCache.DistributedCacheSessionStateStoreProvider, Microsoft.Web.DistributedCache" 
          cacheName="default" 
          dataCacheClientName="default" 
          applicationName="AFCacheSessionState"/>
      </providers>
    </sessionState>
  </system.web>
  <dataCacheClients>
    <dataCacheClient name="default">
      <autoDiscover isEnabled="true" identifier="CacheWorkerRole1" />
    </dataCacheClient>
  </dataCacheClients>
  <cacheDiagnostics>
    <crashDump dumpLevel="Off" dumpStorageQuotaInMB="100" />
  </cacheDiagnostics>
</configuration>

See Also

Concepts

Session State Provider for Azure In-Role Cache