How to: Configure the AppFabric Session State Provider for ASP.NET (AppFabric 1.1 Caching)

This topic explains how to configure an ASP.NET web application to use a provisioned AppFabric cache for session state caching. The configuration is done by modifying the web.config file for the target web application.

Using Microsoft AppFabric 1.1 for Windows Server Caching for Session State

For your ASP.NET Web application to use the AppFabric session state provider, you must add the following elements to your application's web.config file:

  • configSections: This element must be the first element in the configuration file, under the opening configuration tag. It is required for the AppFabric Caching assemblies to function.

  • dataCacheClients: This element is a child of the configuration element. It is used to hold dataCacheClient elements that configure cache clients and specify the cache hosts.

  • sessionState: This element is a child of the system.web element. It specifies to the Web application that it should use Microsoft AppFabric 1.1 for Windows Server to manage session state data. The cacheName attribute specifies the named cache that will be used. The dataCacheClientName attribute specifies which dataCacheClient section to use for the cache configuration.

Warning

We recommend that you secure the web.config file used to specify the names of the cache hosts.

To use Microsoft AppFabric 1.1 for Windows Server caching for session state

  1. First prepare your Visual Studio 2010 project to use Microsoft AppFabric 1.1 for Windows Server Caching. For more information, see Preparing the Cache Client Development Environment (AppFabric 1.1 Caching).

  2. In addition to the normal caching assemblies, also reference the Microsoft.Web.DistributedCache.dll assembly in the Microsoft AppFabric 1.1 for Windows Server Caching installation path.

  3. Copy the configSections element from the example after these steps into your web.config file. Make sure that this element is the first element inside the configuration tags.

  4. Copy the dataCacheClients element from the example after these steps into your web.config file. It should be added after the configSections element, inside the configuration element.

    1. Configure the name and cachePort attributes of the host elements to match the cache servers in your environment. Add or remove host elements as appropriate.
  5. Copy the sessionState element from the example after these steps into your web.config file. It should be positioned inside the system.web element. Specify the cacheName and dataCacheClientName attributes as well as any other required settings.

  6. Determine the identity of the web application. This can be done in IIS Manager on the web servers. Look at the identity of the application pool associated with the web application. Grant this user access to the cache cluster using the Grant-CacheAllowedClientAccount Windows Powershell command.

    Tip

    If the application pool runs as a built-in machine account, such as "NT Authority\Network Service", then you should grant access to the cache cluster for that machine. You can do this by specifying DOMAINNAME\MACHINENAME$ as the account. Note that the "$" is appended to the machine name to indicate that this is the machine account.

Example

This example shows how to configure an ASP.NET Web application to use a cache client to store session data to a distributed cache named default. The cache client in this example is only configured to communicate with one cache host that is named CacheServer1.

  1. First, add the configSections element to the web.config file as the first element in the configuration element:

      <!--configSections must be the FIRST element -->
      <configSections>
        <section name="dataCacheClients"
                 type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core"
                 allowLocation="true" allowDefinition="Everywhere"/>
      </configSections>
    
  2. Second, add the single dataCacheClients element that contains one or more dataCacheClient elements. Add this to the web.config file, after the configSections element. This is where you configure your cache client to meet the needs of your application. For more information, see Application Configuration Settings (AppFabric 1.1 Caching).

      <dataCacheClients>
        <dataCacheClient name="default">
          <hosts>
            <host name="CacheServer1" cachePort="22233" />
          </hosts>
        </dataCacheClient>
      </dataCacheClients>
    
  3. After the configSections and dataCacheClients elements have been added, add the sessionState element to the web.config file, inside the system.web element. This is where you specify which cache the Web application will use to store session state data. Customize the cacheName and dataCacheClientName attributes as well as any other required settings.

    Note that if multiple Web applications need to share the same session state, they should use the same applicationNamme attribute value. Otherwise, you do not need to specify the applicationNamme attribute.

        <sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider" compressionEnabled="false">
          <providers>
            <add name="AppFabricCacheSessionStoreProvider"
                 type="Microsoft.Web.DistributedCache.DistributedCacheSessionStateStoreProvider, Microsoft.Web.DistributedCache"
                 cacheName="default"
                 useBlobMode="true"
                 dataCacheClientName="default"/>
          </providers>
        </sessionState>
    

When it is complete, the Web application's final web.config file will resemble the following example.

<?xml version="1.0"?>

<configuration>
  <configSections>
    <section name="dataCacheClients"
             type="Microsoft.ApplicationServer.Caching.DataCacheClientsSection, Microsoft.ApplicationServer.Caching.Core"
             allowLocation="true" allowDefinition="Everywhere"/>
  </configSections>

  <dataCacheClients>
    <dataCacheClient name="default" channelOpenTimeout="10000">
      <hosts>
        <host name="CacheServer1" cachePort="22233" />
      </hosts>
    </dataCacheClient>
  </dataCacheClients>
  
  <system.web>
    <sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider" compressionEnabled="false">
      <providers>
        <add name="AppFabricCacheSessionStoreProvider"
             type="Microsoft.Web.DistributedCache.DistributedCacheSessionStateStoreProvider, Microsoft.Web.DistributedCache"
             cacheName="default"
             useBlobMode="true"
             dataCacheClientName="default"/>
      </providers>
    </sessionState>
  </system.web>
</configuration>

See Also

Concepts

Session State Provider (AppFabric 1.1 Caching)

  2012-09-12