How to: Configure a Session State Provider (XML) (Velocity)

  • Article

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Microsoft project code named "Velocity" 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 "Velocity," 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 "Velocity" assemblies, and so on. For more information, see How to: Prepare the Development Environment (Velocity).

For your ASP.NET Web application to use the "Velocity" 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 "Velocity" assemblies to function.

  • dataCacheClient: This element is a child of the configuration element. It is used to configure the cache client, enable local cache, and specify the cache hosts. For more information about the cache client, see Cache Clients and Local Cache (Velocity).

  • sessionState: This element is a child of the system.web element. It specifies to the Web application that it should use "Velocity" 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.

Data in the cache is not encrypted and is available to any cache client with the appropriate configuration settings. We highly recommend that you secure the web.config file used to specify the cache client.

To configure a "Velocity" 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. Set the deployment attribute of the dataCacheClient element to specify a simple or routing client. For more information, see Cache Clients and Local Cache (Velocity).

    2. If you want local cache enabled, uncomment and configure the localCache element, a child of the dataCacheClient element. For more information, see How to: Enable Local Cache (XML) (Velocity).

    3. Configure the cache host name, cachePort, and cacheHostName 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.

Example

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

First, add the configSections element to the web.config 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.Data.Caching.DataCacheClientSection,
     CacheBaseLibrary"
     allowLocation="true"
     allowDefinition="Everywhere"/>
  
  <!-- required to read the <fabric> element, when present -->
  <section name="fabric"
     type="System.Data.Fabric.Common.ConfigFile,
     FabricCommon"
     allowLocation="true"
     allowDefinition="Everywhere"/>
</configSections>

Second, add the dataCacheClient element to the web.config, after the configSections element. This is where you configure your cache client to meet the needs of your application. For more information, see Configuring the Cache Client with XML (Velocity).

<!-- routing client -->
<dataCacheClient deployment="routing">

  <!-- (optional) specify local cache 
  <localCache
    isEnabled="true"
    sync="TTLBased"
    objectCount="100000"
    ttlValue="300" />
  -->
  
  <!-- cache host(s) -->
  <hosts>
    <host
       name="CacheServer1"
       cachePort="22233"
       cacheHostName="DistributedCacheService"/>
  </hosts>
</dataCacheClient>

After the configSections and dataCacheClient elements have been added, add the sessionState element to the web.config, inside the system.web element. This is where you specify which cache the Web application will use to store session state data.

<sessionState mode="Custom" customProvider="Velocity">
  <providers>
    <!-- specify the named cache for session data -->
    <add 
      name="Velocity" 
      type="Microsoft.Data.Caching.SessionStoreProvider" 
      cacheName="NamedCache1"/>
  </providers>
</sessionState>

Once 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.Data.Caching.DataCacheClientSection,
       CacheBaseLibrary"
       allowLocation="true"
       allowDefinition="Everywhere"/>
    
    <!-- required to read the <fabric> element, when present -->
    <section name="fabric"
       type="System.Data.Fabric.Common.ConfigFile,
       FabricCommon"
       allowLocation="true"
       allowDefinition="Everywhere"/>
  </configSections>
  
  <!-- routing client -->
  <dataCacheClient deployment="routing">

    <!-- (optional) specify local cache 
    <localCache
      isEnabled="true"
      sync="TTLBased"
      objectCount="100000"
      ttlValue="300" />
    -->
    
    <!-- cache host(s) -->
    <hosts>
      <host
         name="CacheServer1"
         cachePort="22233"
         cacheHostName="DistributedCacheService"/>
    </hosts>
  </dataCacheClient>

  <system.web>
    <sessionState mode="Custom" customProvider="Velocity">
      <providers>
        <!-- specify the named cache for session data -->
        <add 
          name="Velocity" 
          type="Microsoft.Data.Caching.SessionStoreProvider" 
          cacheName="NamedCache1"/>
      </providers>
    </sessionState>
  </system.web>
</configuration>

See Also

Tasks

How to: Get Started with a Simple Client (XML) (Velocity)
How to: Get Started with a Routing Client (XML) (Velocity)
How to: Enable Local Cache (XML) (Velocity)
How to: Set Log Sink Levels (XML) (Velocity)

Concepts

Cache Clients and Local Cache (Velocity)

Other Resources

Using Configuration Methods (Velocity)
Cache Concepts (Velocity)
Programming Guide (Velocity)