Configuring an ASP.NET Session State Provider (Windows Server AppFabric Caching)

Windows Server AppFabric offers a custom session state provider for your ASP.NET Web applications. This lets Web applications spread session objects across the cache cluster, providing scalability. Due to the nature of the caching features of AppFabric, objects that you put in Session must be serializable.

The procedures in this topic assume that you have already prepared your Web application's development environment and set references to the AppFabric caching assemblies, and so on. For more information, see Preparing the Cache Client Development Environment (Windows Server AppFabric Caching).

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.

• dataCacheClient: This element is a child of the configuration element. It is used to configure the cache client and specify the cache hosts. For more information about the cache client, see Developing a Cache Client (Windows Server AppFabric Caching).

• sessionState: This element is a child of the system.web element. It specifies to the Web application that it should use AppFabric to manage session states. The cacheName attribute specifies the named cache that will be used. If you store session data in a cache region, use the regionName attribute to specify the region.

Note

Objects stored in a region will not be load balanced across cache hosts, but will be located on the cache host where the region was created. For this reason, it is not a generally recommended configuration. Regions should only be used when there is a special requirement to locate all session objects on a single host.

Warning

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

To configure an AppFabric session state provider for your Web application

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

2. Copy the dataCacheClient 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.

3. Copy the sessionState element from the example after these steps into your web.config file. It should be positioned inside the system.web element.

4. 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 called NamedCache1. The cache client in this example is only configured to communicate with one cache host that is named CacheServer1.

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>
   <!-- required to read the <dataCacheClient> element -->
   <section name="dataCacheClient"
         type="Microsoft.ApplicationServer.Caching.DataCacheClientSection,
            Microsoft.ApplicationServer.Caching.Core, Version=1.0.0.0, 
            Culture=neutral, PublicKeyToken=31bf3856ad364e35"
         allowLocation="true"
         allowDefinition="Everywhere"/>
</configSections>

Second, add the dataCacheClient element 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 (Windows Server AppFabric Caching).

<!-- cache client -->
<dataCacheClient> 
  <!-- cache host(s) -->
  <hosts>
    <host
       name="CacheServer1"
       cachePort="22233"/>
  </hosts>
</dataCacheClient>

After the configSections and dataCacheClient 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.

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

<sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider">
  <providers>
    <!-- specify the named cache for session data -->
    <add 
      name="AppFabricCacheSessionStoreProvider" 
      type="Microsoft.ApplicationServer.Caching.DataCacheSessionStoreProvider" 
      cacheName="NamedCache1"
      sharedId="SharedApp"/>
  </providers>
</sessionState>

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

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  
  <!--configSections must be the FIRST element -->
  <configSections>
     <!-- required to read the <dataCacheClient> element -->
     <section name="dataCacheClient"
         type="Microsoft.ApplicationServer.Caching.DataCacheClientSection,
            Microsoft.ApplicationServer.Caching.Core, Version=1.0.0.0, 
            Culture=neutral, PublicKeyToken=31bf3856ad364e35"
         allowLocation="true"
         allowDefinition="Everywhere"/>
  </configSections>
  
  <!-- cache client -->
  <dataCacheClient>    
    <!-- cache host(s) -->
    <hosts>
      <host
         name="CacheServer1"
         cachePort="22233"/>
    </hosts>
  </dataCacheClient>

  <system.web>
    <sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider">
      <providers>
        <!-- specify the named cache for session data -->
        <add 
          name="AppFabricCacheSessionStoreProvider" 
          type="Microsoft.ApplicationServer.Caching.DataCacheSessionStoreProvider" 
          cacheName="NamedCache1"
          sharedId="SharedApp"/>
      </providers>
    </sessionState>
  </system.web>
</configuration>

See Also

Concepts

Get Started with a Windows Server AppFabric Cache Client (XML)
Using Configuration Methods (Windows Server AppFabric Caching)
Windows Server AppFabric Caching Concepts
Developing a Cache Client (Windows Server AppFabric Caching)