<!– Copyright © VMware, Inc. 2022. All rights reserved. Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. –>

The Pivotal.GemFire.Session library implements Microsoft’s SessionStateStoreProviderBase API.


To use the GemFire SessionStateProvider requires the following components:


Using GemFire SessionStateProvider in your web application requires:

  • cache.xml: A config file for the GemFire client cache, as shown below, which includes as a minimum, the name of the region to be used for the session state store.
   <pool name="default">
    <locator host="localhost" port="10334"/>

  <region name="<session-region-name>" >
    <region-attributes refid="PROXY" pool-name="default" />
  • This is an optional file that can be used to pass system properties (security parameters, for example) to the GemFire NativeClient.
   # Cache region configuration
   # The cache xml file can be specified here optionally
   # if it is not specified in the Web.config
   # Log file config
   # SSL socket support
   # Security
  • A sessionState element in your application’s config file (Web.config) that references this GemFire SessionStateProvider. In this example we set the region variable to “session-region-name”, but this can be any region dedicated for use by the SessionStateProvider.
    <compilation debug="true" targetFramework="4.5.2"/>
    <httpRuntime targetFramework="4.5"/>
        <add namespace="System.Web.Optimization"/>
        <add assembly="Microsoft.AspNet.Web.Optimization.WebForms" namespace="Microsoft.AspNet.Web.Optimization.WebForms" tagPrefix="webopt"/>
    <sessionState mode="Custom" cookieless="false" timeout="1" customProvider="GemFireSessionProvider">
        <add name="GemFireSessionProvider" type="Pivotal.GemFire.Session.SessionStateStore"
  • Note: The specified region in the Web.Config must either also match a <region> entry in the cache.xml or match a region created programmatically in the client code.
  • add a reference to the included Pivotal.GemFire.Session library to your application’s project
  • add a reference to the included Pivotal.GemFire library to your application’s project (Do not use any other versions.)

  • In your application code, you must initialize and create the client Cache as well as register PDXSerializers. Below is an example of code to go in Application_Start():

   protected void Application_Start(object sender, EventArgs e)

       Properties<string, string> properties = new Properties<string, string>();
       properties.Insert("cache-xml-file", "<path-to-cache>.xml-file\\cache.xml");
       properties.Insert("appdomain-enabled", "true");

       var cacheFactory = CacheFactory.CreateCacheFactory(properties);

       Cache = cacheFactory.Create();
       // chain together serializers
       Serializable.RegisterPdxSerializer(new GetItemExclusiveSerializer(new SessionStateStoreDataSerializer()));
  • If using a custom serializer for a custom domain object, the serializer for the domain object must be added to the serialization chain, as shown below where we show how to chain a CustomDomainObjectSerializer class:
   public class CustomDomainObjectSerializer : ChainedPdxSerializer
       public GetItemExclusiveSerializer(IPdxSerializer next) : base(next)

       override public object FromData(string classname, IPdxReader reader)

       override public bool ToData(object obj, IPdxWriter writer)
  • In the Application_Start() you would need to add it to the serializer chain like so:
  Serializable.RegisterPdxSerializer(new CustomDomainObjectSerializer(new GetItemExclusiveSerializer(new SessionStateStoreDataSerializer())));


Any errors will be displayed in the browser as well as in the Application event logs under the ASP.NET event source. The event viewer can be filtered by event source. More powerful filtering is available via PowerShell. GemFire server-level session tracing can be enabled by setting log-level=finest or log-level=all in the server properties.

For developers testing in Visual Studio

  1. Tools->Options->Projects And Solutions->Web Projects: enable Use 64-bit version of IIS Express
  2. Must use a 64-bit target
  3. Must add the cache.xml to the project and select “Copy Always” in the properties for “Copy to output directory”

Configuring the GemFire Server

To use the GemFire SessionStateProvider configure the GemFire cluster as follows:

This command must be run after the server is started.

gfsh> deploy --jar=INSTALL_DIR/lib/SessionStateStoreFunctions.jar

This command must be run to create a region matching the region attribute value in the Web.config. In this example, we chose the region name “session”, so we provide that to the --name argument below.

gfsh> create region --name="session" --type=PARTITION