Session State Provider

The Pivotal GemFire Session library implements Microsoft’s SessionStateStoreProviderBase API. The session state provider stores session state data in a region on the GemFire server.

To incorporate the GemFire session state provider into your web application:

• Provide a configuration file for your application.
• Set up the application’s development environment.
• Configure the GemFire server.
• Provide for authentication, if your server requires it.

Creating or Changing Configuration Files

Create or modify your client-side configuration files to specify the region in which session state will be stored. Your Native Client distribution includes Web.Config, which you can modify as needed.

Web.Config Example

The native client release for Windows contains a Web.Config file similar to the following. The configuration file:

• Specifies a sessionState element that references the GemFire session state provider.
• Sets the region variable to sessionStateRegion, the region dedicated for use by the session state provider.
• In this example, the config file specifies one locator using the parameter pair
  • locator-host="localhost" and locator-port="10334".
  • To specify multiple locators, instead, use a single locators parameter with the form locators="locator1[port1],locator2[port2]". The two forms are mutually exclusive.

• Assuming that the server requires secure connections, sets four SSL-related parameters:

  • ssl-enabled
  • ssl-keystore
  • ssl-keystore-password
  • ssl-truststore

  <system.web>
  <compilation debug="true" targetFramework="4.5.2"/>
  <httpRuntime targetFramework="4.5"/>
  <pages>
    <namespaces>
      <add namespace="System.Web.Optimization"/>
    </namespaces>
    <controls>
      <add assembly="Microsoft.AspNet.Web.Optimization.WebForms" namespace="Microsoft.AspNet.Web.Optimization.WebForms" tagPrefix="webopt"/>
    </controls>
  </pages>
  <sessionState mode="Custom" cookieless="false" timeout="1" customProvider="GemFireSessionProvider">
    <providers>
      <add name="GemFireSessionProvider" type="Pivotal.GemFire.Session.SessionStateStore"
       region="sessionStateRegion"
       locator-host="localhost"
       locator-port="10334"
       pool-name="default"
       ssl-enabled="true"
       ssl-keystore="C:/gemfire-dotnetsession/SampleWebApp/Security/client_keystore.password.pem"
       ssl-keystore-password="gemstone"
       ssl-truststore="C:/gemfire-dotnetsession/SampleWebApp/Security/client_truststore.pem"
       log-file="C:/gemfire-dotnetsession/SampleWebApp/SampleWebApp.log"
       log-level="fine"
       />
    </providers>
  </sessionState>
  </system.web>
  

Modifying the Application’s Development Environment

In your development environment:

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

  Note: You must use the matched pair of Pivotal.GemFire.Session and Pivotal.GemFire libraries from the same distribution of the GemFire Native Client. Do not mix two different versions.

For developers testing in Visual Studio

• Under Tools->Options->Projects And Solutions->Web Projects, enable the property “Use 64-bit version of IIS Express”.
• You must use a 64-bit target.

Configuring the GemFire Server

To use the GemFire session state provider, the server-based region name and the region name you have specified in Web.config must match. For example, the following gfsh create region command uses the --name parameter to create a region named sessionStateRegion.

gfsh> create region --name="sessionStateRegion" --type=PARTITION`

The Microsoft SessionStateStoreProviderBase API relies on the app developer to provide server-side functions to save and restore session state. This distribution of the Native Client provides implementations of the expected functions, packaged as a JAR file in INSTALL_DIR/lib/SessionStateStoreFunctions.jar.

Copy the JAR file to your server then, after the server is started, use gfsh to deploy the session state functions on the server:

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

Configure Server-Side Logging

The GemFire server-side session functions provide tracing-level logging in case you need such details during app development. Trace-level logging can be enabled by setting log-level=finest or log-level=all in the server properties. (These log-level settings generate a log of very detailed log entries. Remember to restore logging to a higher, less verbose level (such as log-level=info, when the detail is no longer needed.) Refer to Logging in the GemFire User Guide for more information on server-side logging.

Providing Authentication (optional)

If expected by the server, your client application must provide authentication. Implement the IAuthInitialize interface to specify credentials. For example:

protected void Application_Start(object sender, EventArgs e)
{
    SessionStateStore.AuthInitialize = new BasicAuthInitialize("john", "secret");
    RouteConfig.RegisterRoutes(RouteTable.Routes);
    BundleConfig.RegisterBundles(BundleTable.Bundles);
}

public class BasicAuthInitialize : IAuthInitialize
{
    private string _username;
    private string _password;

    public BasicAuthInitialize(string username, string password)
    {
        _username = username;
        _password = password;
    }

    public void Close()
    {
    }

    public Properties<string, object> GetCredentials(Properties<string, string> props, string server)
    {
        var credentials = new Properties<string, object>();

        credentials.Insert("security-username", _username);
        credentials.Insert("security-password", _password);

        return credentials;
    }
}