DynamoDBSessionManager

Overview

The DynamoDBSessionManager class represents a session manager that stores session data in the DynamoDB NoSQL database.

Sessions are stored out-of-process and are able to survive a service restart. Session data can be shared between several services of the same type thus allowing to implement load balancing mechanisms like Round Robin etc.

There are two things one should consider before using the DynamoDBSessionManager component to store session data:

  1. For obvoius reasons, session access performance is considerably lower for the DynamoDBSessionManager compared to the In-Memory Session Manager, because accessing data stored in the DynamoDB takes much more time than accessing a session object stored in memory.

  2. Not all data types can be stored in a DynamoDB session. Supported types are:

  3. Primitive values:

    • Binary
    • Boolean
    • Byte
    • Currency
    • DateTime
    • Decimal
    • Double
    • Guid
    • Int8
    • Int16
    • Int32
    • Int64
    • String
  4. Classes inherited from the ComplexType class. In this case methods ComplexType and ComplexType are used to serialize/deserialize data
  5. All .NET classes marked with the Serializable attribute. In this case .NET serialization facility will be used
  6. Arrays of types listed above

The DynamoDBSessionManager class requires an active Amazon Web Services subscription. While it is possible to use the DynamoDBSessionManager session manager with local DynamoDB emulator it is strongly not recommended for production use (as the DynamoDB Local Test Tool is a development tool, not a production-use database).

The DynamoDBSessionManager class supports 2 different ways of setting up the DynamoDB access:

Via providing AWS access key and AWS secret key via properties of the DynamoDBSessionManager instance.

Via providing AWS access key and AWS secret key via application configuration file:

<?xml version="1.0" encoding="utf-8" ?>

Also either RegionName or ServiceURL properties should be set.

To store session data DynamoDBSessionManager class uses DynamoDB table Sessions where should be defined HASH key of type String. Check the CreateStorageIfNeeded property definition to find out how to let the DynamoDBSessionManager instance to automatically create the session storage table if needed.

Note: The Initialize method should be called once the properties of the session manager instance are set. This method establishes connection to the DynamoDB services and recrreates the session storage table if needed.

Location


 

constructor

Creates a new instance of the DynamoDBSessionManager class.

 

constructor

 

DynamoDBSessionManager()

 

Sub New()

constructor (IContainer)

Creates a new instance of the DynamoDBSessionManager class and adds the newly created instance to the provided component container.

 

constructor(container: IContainer)

 

DynamoDBSessionManager(IContainer container)

 

Sub New(container As IContainer)

Parameters:

  • container: Components container

constructor (Boolean)

 

constructor(register: Boolean)

 

DynamoDBSessionManager(Boolean register)

 

Sub New(register As Boolean)

Parameters:

  • register:

constructor (Boolean, Boolean)  protected    (declared in SessionManager)

 

constructor(register: Boolean; initializeSessionExpirationTimer: Boolean)

 

DynamoDBSessionManager(Boolean register, Boolean initializeSessionExpirationTimer)

 

Sub New(register As Boolean, initializeSessionExpirationTimer As Boolean)

Parameters:

  • register:
  • initializeSessionExpirationTimer:

ApplicationId

Gets or sets the so-called Application type ID.

This property was introduced to prevent access to sessions not owned by the current server application. Only servers that share the same ApplicationId value have access to the each other's sessions.

 

property ApplicationId: Guid read write;

 

Guid ApplicationId { get; set; }

 

Property ApplicationId() As Guid

AWSAccessKey

Gets or sets AWS access key.

Please refer to the Amazon Web Services documentation for additional information on AWS access credentials.

 

property AWSAccessKey: String read write;

 

String AWSAccessKey { get; set; }

 

Property AWSAccessKey() As String

AWSSecretKey

Gets or sets AWS secret key.

Please refer to the Amazon Web Services documentation for additional information on AWS access credentials.

 

property AWSSecretKey: String read write;

 

String AWSSecretKey { get; set; }

 

Property AWSSecretKey() As String

CreateNewSession  protected

Creates a new session instance with the provided Session ID.

At this point, the session is created locally without storing it in the DynamoDB storage.

 

method CreateNewSession(sessionId: Guid): ISession

 

ISession CreateNewSession(Guid sessionId)

 

Function CreateNewSession(sessionId As Guid) As ISession

Parameters:

  • sessionId: Session Id

CreateStorageIfNeeded

Gets or set a flag indicating whether the DynamoDB session storage table should be auto-created on session manager startup.

 

property CreateStorageIfNeeded: Boolean read write;

 

Boolean CreateStorageIfNeeded { get; set; }

 

Property CreateStorageIfNeeded() As Boolean

DestroySession (ISession)    (declared in SessionManager)

 

method DestroySession(session: ISession)

 

void DestroySession(ISession session)

 

Sub DestroySession(session As ISession)

Parameters:

  • session:

DestroySession (Guid)    (declared in SessionManager)

 

method DestroySession(sessionId: Guid)

 

void DestroySession(Guid sessionId)

 

Sub DestroySession(sessionId As Guid)

Parameters:

  • sessionId:

Dispose  protected    (declared in SessionManager)

 

method Dispose(disposing: Boolean)

 

void Dispose(Boolean disposing)

 

Sub Dispose(disposing As Boolean)

Parameters:

  • disposing:

ExpireSessions

Expires all sessions in the Session Manager that have exceeded the timeout.

Note: Session Manager will regularly check for expired sessions automatically, but you can use this method to trigger an expiration cycle manually.

 

method ExpireSessions

 

void ExpireSessions()

 

Sub ExpireSessions()

GetAllSessions

Returns identifiers of active sessions.

Only sessions stored with a valid ApplicationId are enumerated.

Note: This is a lengthly and resource-heavy operation as it requires the full scan of the undelying DynamoDB table.

 

method GetAllSessions: IList<Guid>

 

IList<Guid> GetAllSessions()

 

Function GetAllSessions() As IList<Guid>

GetExistingSession    (declared in SessionManager)

Returns existing session with provided Id or null in case the session cannot be found. Depending on the updateTime parameter value updates the session's LastaccessedTime attribute.

 

method GetExistingSession(sessionId: Guid; updateTime: Boolean): ISession

 

ISession GetExistingSession(Guid sessionId, Boolean updateTime)

 

Function GetExistingSession(sessionId As Guid, updateTime As Boolean) As ISession

Parameters:

  • sessionId: Session Id
  • updateTime: Flag indicating whether session's LastAccessedTime attribute should be updated

GetSession    (declared in SessionManager)

Returns session with provided Id. If there is no session stored with the provided Id then new session is created.

 

method GetSession(sessionId: Guid): ISession

 

ISession GetSession(Guid sessionId)

 

Function GetSession(sessionId As Guid) As ISession

Parameters:

  • sessionId: Session Id

Initialize

Initializes components needed to communicate with the DynamoDB services.

Depending on the value of the CreateStorageIfNeeded property session storage table can be automatically created.

Note: Creating session storage table is a lengthly operation and can take up to one minute.

 

method Initialize

 

void Initialize()

 

Sub Initialize()

IsOutOfProcess

Gets a flag indicating that session manager uses out-of-process session storage.

Returns true.

 

property IsOutOfProcess: Boolean read;

 

Boolean IsOutOfProcess { get; }

 

ReadOnly Property IsOutOfProcess() As Boolean

LocateExistingSession  protected

Retrieves the session with the provided ID from the DynamoDB table. Returns null if session with the provided ID was not found.

 

method LocateExistingSession(sessionId: Guid; updateTime: Boolean): ISession

 

ISession LocateExistingSession(Guid sessionId, Boolean updateTime)

 

Function LocateExistingSession(sessionId As Guid, updateTime As Boolean) As ISession

Parameters:

  • sessionId: Session Id
  • updateTime:

OnSessionCreated    (declared in SessionManager)

Gets triggered after a new Session has been created. You can use it to perform initialization functions or fill the session with default values.

 

event OnSessionCreated: SessionEventHandler;
delegate:  method OnSessionCreated(sender: Object; e: SessionEventArgs)

 

delegate SessionEventHandler OnSessionCreated()
delegate:  void OnSessionCreated(Object sender, SessionEventArgs e)

 

Event OnSessionCreated As SessionEventHandler
delegate:  Sub OnSessionCreated(sender As Object, e As SessionEventArgs)

OnSessionDestroyed    (declared in SessionManager)

Gets triggered after a new Session has been manually destroyed. You can use it to perform cleanup for a specific session id.

Note: The session has already been Disposed when the OnSessionDestroyed event fires. This event will not fire for sessions that expire.

 

event OnSessionDestroyed: SessionIDEventHandler;
delegate:  method OnSessionDestroyed(sender: Object; e: SessionIDEventArgs)

 

delegate SessionIDEventHandler OnSessionDestroyed()
delegate:  void OnSessionDestroyed(Object sender, SessionIDEventArgs e)

 

Event OnSessionDestroyed As SessionIDEventHandler
delegate:  Sub OnSessionDestroyed(sender As Object, e As SessionIDEventArgs)

OnSessionExpired    (declared in SessionManager)

Gets triggered after a new Session has been expired. You can use it to perform cleanup and/or inspect the values of the expired session.

Note: The session has already been Disposed when the OnSessionExpired event fires. This event will not fire for sessions that are manually destroyed.

 

event OnSessionExpired: SessionEventHandler;
delegate:  method OnSessionExpired(sender: Object; e: SessionEventArgs)

 

delegate SessionEventHandler OnSessionExpired()
delegate:  void OnSessionExpired(Object sender, SessionEventArgs e)

 

Event OnSessionExpired As SessionEventHandler
delegate:  Sub OnSessionExpired(sender As Object, e As SessionEventArgs)

ReadCapacityUnits

Gets or sets write capacity units set if the new session storage table is created. This property doesn't affect provisioning settings of existing session storage tables.

The default value of this property is 5.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB capacity units.

 

property ReadCapacityUnits: Int32 read write;

 

Int32 ReadCapacityUnits { get; set; }

 

Property ReadCapacityUnits() As Int32

RegionName

Gets or sets the region to use DynamoDB in.

The default value is us-east-1.

Possible values are

  • us-east-1
  • us-west-1
  • us-west-2
  • eu-west-1
  • ap-northeast-1
  • ap-southeast-1

Note: Changing value of this property won't have any effect after the %%DynamoDBSessionManager%Initialize%% method has beed executed.

Please refer to the Amazon Web Services documentation for additional information on AWS regions.

 

property RegionName: String read write;

 

String RegionName { get; set; }

 

Property RegionName() As String

ReleaseSession

Releases the previously acquired session. The session data is serialized and stored in the underlying DynamoDB table.

In most cases, this method is called automatically when a service is deactivated.

 

method ReleaseSession(session: ISession)

 

void ReleaseSession(ISession session)

 

Sub ReleaseSession(session As ISession)

Parameters:

  • session: Session instance

ServiceURL

Gets or sets URL used to access the DynamoDB service. Takes precendence over the RegionName property.

In most cases it is recommended to set the RegionName property instead of this property. However this property can be used for setting the local DynamoDB emulator as a data storage service.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB local emulator.

 

property ServiceURL: String read write;

 

String ServiceURL { get; set; }

 

Property ServiceURL() As String

SessionCount  protected

Gets the number of sessions stored in the DynamoDB session storage.

Note: This is a lengthly and resource-heavy operation as it requires the full scan of the undelying DynamoDB table.

 

property SessionCount: Int32 read;

 

Int32 SessionCount { get; }

 

ReadOnly Property SessionCount() As Int32

Timeout

Gets or sets session timeout.

 

property Timeout: Int32 read write;

 

Int32 Timeout { get; set; }

 

Property Timeout() As Int32

TriggerOnSessionCreated  protected    (declared in SessionManager)

 

method TriggerOnSessionCreated(e: SessionEventArgs)

 

void TriggerOnSessionCreated(SessionEventArgs e)

 

Sub TriggerOnSessionCreated(e As SessionEventArgs)

Parameters:

  • e:

TriggerOnSessionDestroyed  protected    (declared in SessionManager)

 

method TriggerOnSessionDestroyed(e: SessionIDEventArgs)

 

void TriggerOnSessionDestroyed(SessionIDEventArgs e)

 

Sub TriggerOnSessionDestroyed(e As SessionIDEventArgs)

Parameters:

  • e:

TriggerOnSessionExpired  protected    (declared in SessionManager)

 

method TriggerOnSessionExpired(e: SessionEventArgs)

 

void TriggerOnSessionExpired(SessionEventArgs e)

 

Sub TriggerOnSessionExpired(e As SessionEventArgs)

Parameters:

  • e:

WriteCapacityUnits

Gets or sets read capacity units set if the new session storage table is created. This property doesn't affect provisioning settings of existing session storage tables.

The default value of this property is 10.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB capacity units.

 

property WriteCapacityUnits: Int32 read write;

 

Int32 WriteCapacityUnits { get; set; }

 

Property WriteCapacityUnits() As Int32

 

ApplicationId

Gets or sets the so-called Application type ID.

This property was introduced to prevent access to sessions not owned by the current server application. Only servers that share the same ApplicationId value have access to the each other's sessions.

 

property ApplicationId: Guid read write;

 

Guid ApplicationId { get; set; }

 

Property ApplicationId() As Guid

AWSAccessKey

Gets or sets AWS access key.

Please refer to the Amazon Web Services documentation for additional information on AWS access credentials.

 

property AWSAccessKey: String read write;

 

String AWSAccessKey { get; set; }

 

Property AWSAccessKey() As String

AWSSecretKey

Gets or sets AWS secret key.

Please refer to the Amazon Web Services documentation for additional information on AWS access credentials.

 

property AWSSecretKey: String read write;

 

String AWSSecretKey { get; set; }

 

Property AWSSecretKey() As String

CreateStorageIfNeeded

Gets or set a flag indicating whether the DynamoDB session storage table should be auto-created on session manager startup.

 

property CreateStorageIfNeeded: Boolean read write;

 

Boolean CreateStorageIfNeeded { get; set; }

 

Property CreateStorageIfNeeded() As Boolean

IsOutOfProcess

Gets a flag indicating that session manager uses out-of-process session storage.

Returns true.

 

property IsOutOfProcess: Boolean read;

 

Boolean IsOutOfProcess { get; }

 

ReadOnly Property IsOutOfProcess() As Boolean

ReadCapacityUnits

Gets or sets write capacity units set if the new session storage table is created. This property doesn't affect provisioning settings of existing session storage tables.

The default value of this property is 5.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB capacity units.

 

property ReadCapacityUnits: Int32 read write;

 

Int32 ReadCapacityUnits { get; set; }

 

Property ReadCapacityUnits() As Int32

RegionName

Gets or sets the region to use DynamoDB in.

The default value is us-east-1.

Possible values are

  • us-east-1
  • us-west-1
  • us-west-2
  • eu-west-1
  • ap-northeast-1
  • ap-southeast-1

Note: Changing value of this property won't have any effect after the %%DynamoDBSessionManager%Initialize%% method has beed executed.

Please refer to the Amazon Web Services documentation for additional information on AWS regions.

 

property RegionName: String read write;

 

String RegionName { get; set; }

 

Property RegionName() As String

ServiceURL

Gets or sets URL used to access the DynamoDB service. Takes precendence over the RegionName property.

In most cases it is recommended to set the RegionName property instead of this property. However this property can be used for setting the local DynamoDB emulator as a data storage service.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB local emulator.

 

property ServiceURL: String read write;

 

String ServiceURL { get; set; }

 

Property ServiceURL() As String

SessionCount  protected

Gets the number of sessions stored in the DynamoDB session storage.

Note: This is a lengthly and resource-heavy operation as it requires the full scan of the undelying DynamoDB table.

 

property SessionCount: Int32 read;

 

Int32 SessionCount { get; }

 

ReadOnly Property SessionCount() As Int32

Timeout

Gets or sets session timeout.

 

property Timeout: Int32 read write;

 

Int32 Timeout { get; set; }

 

Property Timeout() As Int32

WriteCapacityUnits

Gets or sets read capacity units set if the new session storage table is created. This property doesn't affect provisioning settings of existing session storage tables.

The default value of this property is 10.

Please refer to the Amazon Web Services documentation for additional information on DynamoDB capacity units.

 

property WriteCapacityUnits: Int32 read write;

 

Int32 WriteCapacityUnits { get; set; }

 

Property WriteCapacityUnits() As Int32

 

constructor

Creates a new instance of the DynamoDBSessionManager class.

 

constructor

 

DynamoDBSessionManager()

 

Sub New()

constructor (IContainer)

Creates a new instance of the DynamoDBSessionManager class and adds the newly created instance to the provided component container.

 

constructor(container: IContainer)

 

DynamoDBSessionManager(IContainer container)

 

Sub New(container As IContainer)

Parameters:

  • container: Components container

constructor (Boolean)

 

constructor(register: Boolean)

 

DynamoDBSessionManager(Boolean register)

 

Sub New(register As Boolean)

Parameters:

  • register:

constructor (Boolean, Boolean)  protected    (declared in SessionManager)

 

constructor(register: Boolean; initializeSessionExpirationTimer: Boolean)

 

DynamoDBSessionManager(Boolean register, Boolean initializeSessionExpirationTimer)

 

Sub New(register As Boolean, initializeSessionExpirationTimer As Boolean)

Parameters:

  • register:
  • initializeSessionExpirationTimer:

CreateNewSession  protected

Creates a new session instance with the provided Session ID.

At this point, the session is created locally without storing it in the DynamoDB storage.

 

method CreateNewSession(sessionId: Guid): ISession

 

ISession CreateNewSession(Guid sessionId)

 

Function CreateNewSession(sessionId As Guid) As ISession

Parameters:

  • sessionId: Session Id

DestroySession (ISession)    (declared in SessionManager)

 

method DestroySession(session: ISession)

 

void DestroySession(ISession session)

 

Sub DestroySession(session As ISession)

Parameters:

  • session:

DestroySession (Guid)    (declared in SessionManager)

 

method DestroySession(sessionId: Guid)

 

void DestroySession(Guid sessionId)

 

Sub DestroySession(sessionId As Guid)

Parameters:

  • sessionId:

Dispose  protected    (declared in SessionManager)

 

method Dispose(disposing: Boolean)

 

void Dispose(Boolean disposing)

 

Sub Dispose(disposing As Boolean)

Parameters:

  • disposing:

ExpireSessions

Expires all sessions in the Session Manager that have exceeded the timeout.

Note: Session Manager will regularly check for expired sessions automatically, but you can use this method to trigger an expiration cycle manually.

 

method ExpireSessions

 

void ExpireSessions()

 

Sub ExpireSessions()

GetAllSessions

Returns identifiers of active sessions.

Only sessions stored with a valid ApplicationId are enumerated.

Note: This is a lengthly and resource-heavy operation as it requires the full scan of the undelying DynamoDB table.

 

method GetAllSessions: IList<Guid>

 

IList<Guid> GetAllSessions()

 

Function GetAllSessions() As IList<Guid>

GetExistingSession    (declared in SessionManager)

Returns existing session with provided Id or null in case the session cannot be found. Depending on the updateTime parameter value updates the session's LastaccessedTime attribute.

 

method GetExistingSession(sessionId: Guid; updateTime: Boolean): ISession

 

ISession GetExistingSession(Guid sessionId, Boolean updateTime)

 

Function GetExistingSession(sessionId As Guid, updateTime As Boolean) As ISession

Parameters:

  • sessionId: Session Id
  • updateTime: Flag indicating whether session's LastAccessedTime attribute should be updated

GetSession    (declared in SessionManager)

Returns session with provided Id. If there is no session stored with the provided Id then new session is created.

 

method GetSession(sessionId: Guid): ISession

 

ISession GetSession(Guid sessionId)

 

Function GetSession(sessionId As Guid) As ISession

Parameters:

  • sessionId: Session Id

Initialize

Initializes components needed to communicate with the DynamoDB services.

Depending on the value of the CreateStorageIfNeeded property session storage table can be automatically created.

Note: Creating session storage table is a lengthly operation and can take up to one minute.

 

method Initialize

 

void Initialize()

 

Sub Initialize()

LocateExistingSession  protected

Retrieves the session with the provided ID from the DynamoDB table. Returns null if session with the provided ID was not found.

 

method LocateExistingSession(sessionId: Guid; updateTime: Boolean): ISession

 

ISession LocateExistingSession(Guid sessionId, Boolean updateTime)

 

Function LocateExistingSession(sessionId As Guid, updateTime As Boolean) As ISession

Parameters:

  • sessionId: Session Id
  • updateTime:

ReleaseSession

Releases the previously acquired session. The session data is serialized and stored in the underlying DynamoDB table.

In most cases, this method is called automatically when a service is deactivated.

 

method ReleaseSession(session: ISession)

 

void ReleaseSession(ISession session)

 

Sub ReleaseSession(session As ISession)

Parameters:

  • session: Session instance

TriggerOnSessionCreated  protected    (declared in SessionManager)

 

method TriggerOnSessionCreated(e: SessionEventArgs)

 

void TriggerOnSessionCreated(SessionEventArgs e)

 

Sub TriggerOnSessionCreated(e As SessionEventArgs)

Parameters:

  • e:

TriggerOnSessionDestroyed  protected    (declared in SessionManager)

 

method TriggerOnSessionDestroyed(e: SessionIDEventArgs)

 

void TriggerOnSessionDestroyed(SessionIDEventArgs e)

 

Sub TriggerOnSessionDestroyed(e As SessionIDEventArgs)

Parameters:

  • e:

TriggerOnSessionExpired  protected    (declared in SessionManager)

 

method TriggerOnSessionExpired(e: SessionEventArgs)

 

void TriggerOnSessionExpired(SessionEventArgs e)

 

Sub TriggerOnSessionExpired(e As SessionEventArgs)

Parameters:

  • e:

 

OnSessionCreated    (declared in SessionManager)

Gets triggered after a new Session has been created. You can use it to perform initialization functions or fill the session with default values.

 

event OnSessionCreated: SessionEventHandler;
delegate:  method OnSessionCreated(sender: Object; e: SessionEventArgs)

 

delegate SessionEventHandler OnSessionCreated()
delegate:  void OnSessionCreated(Object sender, SessionEventArgs e)

 

Event OnSessionCreated As SessionEventHandler
delegate:  Sub OnSessionCreated(sender As Object, e As SessionEventArgs)

OnSessionDestroyed    (declared in SessionManager)

Gets triggered after a new Session has been manually destroyed. You can use it to perform cleanup for a specific session id.

Note: The session has already been Disposed when the OnSessionDestroyed event fires. This event will not fire for sessions that expire.

 

event OnSessionDestroyed: SessionIDEventHandler;
delegate:  method OnSessionDestroyed(sender: Object; e: SessionIDEventArgs)

 

delegate SessionIDEventHandler OnSessionDestroyed()
delegate:  void OnSessionDestroyed(Object sender, SessionIDEventArgs e)

 

Event OnSessionDestroyed As SessionIDEventHandler
delegate:  Sub OnSessionDestroyed(sender As Object, e As SessionIDEventArgs)

OnSessionExpired    (declared in SessionManager)

Gets triggered after a new Session has been expired. You can use it to perform cleanup and/or inspect the values of the expired session.

Note: The session has already been Disposed when the OnSessionExpired event fires. This event will not fire for sessions that are manually destroyed.

 

event OnSessionExpired: SessionEventHandler;
delegate:  method OnSessionExpired(sender: Object; e: SessionEventArgs)

 

delegate SessionEventHandler OnSessionExpired()
delegate:  void OnSessionExpired(Object sender, SessionEventArgs e)

 

Event OnSessionExpired As SessionEventHandler
delegate:  Sub OnSessionExpired(sender As Object, e As SessionEventArgs)