AWS Guide for .NET Developers

Managing ASP.NET Session State with Amazon DynamoDB

ASP.NET applications often store session state data in memory. However, this approach doesn't scale well. After the application grows beyond a single web server, the session state must be shared between servers. A common solution is to set up a dedicated session-state server with Microsoft SQL Server, but this approach also has drawbacks. You must administer another machine, the session-state server is a single point of failure, and the session-state server itself can become a performance bottleneck.

DynamoDB provides an effective solution for sharing session state across web servers without incurring any of these drawbacks.


Regardless of the solution you choose, be aware that DynamoDB enforces limits on the size of an item. None of the records you store in DynamoDB can exceed this limit. For more information, see Limits in DynamoDB in the Amazon DynamoDB Developer Guide.

The AWS SDK for .NET includes AWS.SessionProvider.dll, which contains an ASP.NET session state provider. It also includes the AmazonDynamoDBSessionProviderSample sample, which demonstrates how to use DynamoDB as a session state provider.

For more information about using session state with ASP.NET applications, see the MSDN documentation.

Create the ASP.NET_SessionState Table

When your application starts, it looks for a DynamoDB table that's named, by default, ASP.NET_SessionState. We recommend you create this table before you run your application for the first time.

  1. Choose Create Table. The Create Table wizard opens.

  2. For Table name, enter ASP.NET_SessionState.

  3. For Primary key, enter SessionId and set the type to String.

  4. When all your options are entered as you want them, choose Create.

The ASP.NET_SessionState table is ready for use when its status changes from CREATING to ACTIVE.


If you don't create the table in advance, the session state provider creates the table during its initialization. See the following web.config options for a list of attributes that act as configuration parameters for the session state table. If the provider creates the table, it uses these parameters.

Configure the Session State Provider

  1. Add references to both AWSSDK.dll and AWS.SessionProvider.dll to your Visual Studio ASP.NET project. These assemblies are available by installing the AWS SDK for .NET. You can also install them by using NuGet.

    In earlier versions of the SDK, the functionality for the session state provider was contained in AWS.Extension.dll. To improve usability, the functionality was moved to AWS.SessionProvider.dll. For more information, see the blog post .

  2. Edit your application's Web.config file. In the system.web element, replace the existing sessionState element with the following XML fragment.

    <sessionState timeout="20" mode="Custom" customProvider="DynamoDBSessionStoreProvider"> <providers> <add name="DynamoDBSessionStoreProvider" type="Amazon.SessionProvider.DynamoDBSessionStateStore" AWSProfileName="{profile_name}" Region="us-west-2" /> </providers> </sessionState>

    The profile represents the AWS credentials that are used to communicate with DynamoDB to store and retrieve the session state. If you are using the AWS SDK for .NET and are specifying a profile in the appSettings section of your application's Web.config file, you don't need to specify a profile in the providers section. The AWS .NET client code will discover it at run time. For more information, see net-dg-config.

    If the web server is running on an Amazon EC2 instance configured to use IAM roles for EC2 instances, you don't need to specify any credentials in the Web.config file. In this case, the AWS .NET client will use the IAM role credentials. For more information, see net-dg-roles and net-dg-ddb-sess-security.

Web.config Options

You can use the following configuration attributes in the providers section of your Web.config file:


Access key ID to use. This can be set in the providers or appSettings section. We strongly recommend not using this setting. Instead, specify credentials by using AWSProfileName to specify a profile.


Secret key to use. This can be set in the providers or appSettings section. We recommend not using this setting. Instead, specify credentials by using AWSProfileName to specify a profile.


The profile name associated with the credentials you want to use. For more information, see Configuring Your AWS SDK for .NET Application.


Required string attribute. The AWS Region in which to use DynamoDB. For a list of AWS Regions, see Regions and Endpoints: DynamoDB.


Optional string attribute. The value of the Application attribute is used to partition the session data in the table so that the table can be used for more than one application.


Optional string attribute. The name of the table used to store session data. The default is ASP.NET_SessionState.


Optional int attribute. The read capacity units to use if the provider creates the table. The default is 10.


Optional int attribute. The write capacity units to use if the provider creates the table. The default is 5.


Optional boolean attribute. The CreateIfNotExist attribute controls whether the provider will automatically create the table if it doesn't exist. The default is true. If this flag is set to false and the table doesn't exist, an exception is thrown.

Security Considerations

After the DynamoDB table is created and the application is configured, you can use sessions as you would with any other session provider.

As a security best practice, we recommend you run your applications with the credentials of an IAM user. You can use the IAM Management Console or the AWS Toolkit for Visual Studio to create IAM users and define access policies.

The session state provider needs to be able to call the DeleteItem, DescribeTable, GetItem, PutItem, and UpdateItem operations for the table that stores the session data. You can use the sample policy below to restrict the IAM user to only the operations needed by the provider for an instance of DynamoDB running in us-east-1.

{ "Version" : "2012-10-17", "Statement" : [ { "Sid" : "1", "Effect" : "Allow", "Action" : [ "dynamodb:DeleteItem", "dynamodb:DescribeTable", "dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem" ], "Resource" : "arn:aws:dynamodb:|region_api_default|:{<YOUR-AWS-ACCOUNT-ID>}:table/ASP.NET_SessionState" } ] }