Introduction to session and application state in ASP.NET Core
By Rick Anderson, Steve Smith, and Diana LaRose
HTTP is a stateless protocol. A web server treats each HTTP request as an independent request and does not retain user values from previous requests. This article discusses different ways to preserve application and session state between requests.
Session state
Session state is a feature in ASP.NET Core that you can use to save and store user data while the user browses your web app. Consisting of a dictionary or hash table on the server, session state persists data across requests from a browser. The session data is backed by a cache.
ASP.NET Core maintains session state by giving the client a cookie that contains the session ID, which is sent to the server with each request. The server uses the session ID to fetch the session data. Because the session cookie is specific to the browser, you cannot share sessions across browsers. Session cookies are deleted only when the browser session ends. If a cookie is received for an expired session, a new session that uses the same session cookie is created.
The server retains a session for a limited time after the last request. You can either set the session timeout or use the default value of 20 minutes. Session state is ideal for storing user data that is specific to a particular session but doesn’t need to be persisted permanently. Data is deleted from the backing store either when you call Session.Clear or when the session expires in the data store. The server does not know when the browser is closed or when the session cookie is deleted.
警告
Do not store sensitive data in session. The client might not close the browser and clear the session cookie (and some browsers keep session cookies alive across windows). Also, a session might not be restricted to a single user; the next user might continue with the same session.
The in-memory session provider stores session data on the local server. If you plan to run your web app on a server farm, you must use sticky sessions to tie each session to a specific server. The Windows Azure Web Sites platform defaults to sticky sessions (Application Request Routing or ARR). However, sticky sessions can affect scalability and complicate web app updates. A better option is to use the Redis or SQL Server distributed caches, which don't require sticky sessions. For more information, see Working with a Distributed Cache. For details on setting up service providers, see Configuring Session later in this article.
The remainder of this section describes the options for storing user data.
TempData
ASP.NET Core MVC exposes the TempData property on a controller. This property stores data for only a single request after the current one.TempData is particularly useful for redirection, when data is needed for more than a single request. TempData is built on top of session state.
Cookie-based TempData provider
In ASP.NET Core 1.1 and higher, you can use the cookie-based TempData provider to store a user's TempData in a cookie. To enable the cookie-based TempData provider, register the CookieTempDataProvider service in ConfigureServices:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Add CookieTempDataProvider after AddMvc and include ViewFeatures.
// using Microsoft.AspNetCore.Mvc.ViewFeatures;
services.AddSingleton<ITempDataProvider, CookieTempDataProvider>();
}
The cookie data is encoded with the Base64UrlTextEncoder. Because the cookie is encrypted and chunked, the single cookie size limit does not apply. The cookie data is not compressed, because compressing encryped data can lead to security problems such as the CRIME and BREACH attacks. For more information on the cookie-based TempData provider, see CookieTempDataProvider.
Query strings
You can pass a limited amount of data from one request to another by adding it to the new request’s query string. This is useful for capturing state in a persistent manner that allows links with embedded state to be shared through email or social networks. However, for this reason, you should never use query strings for sensitive data. In addition to being easily shared, including data in query strings can create opportunities for Cross-Site Request Forgery (CSRF) attacks, which can trick users into visiting malicious sites while authenticated. Attackers can then steal user data from your app or take malicious actions on behalf of the user. Any preserved application or session state must protect against CSRF attacks. For more information on CSRF attacks, see Preventing Cross-Site Request Forgery (XSRF/CSRF) Attacks in ASP.NET Core.
Post data and hidden fields
Data can be saved in hidden form fields and posted back on the next request. This is common in multipage forms. However, because the client can potentially tamper with the data, the server must always revalidate it.
Cookies
Cookies provide a way to store user-specific data in web applications. Because cookies are sent with every request, their size should be kept to a minimum. Ideally, only an identifier should be stored in a cookie with the actual data stored on the server. Most browsers restrict cookies to 4096 bytes. In addition, only a limited number of cookies are available for each domain.
Because cookies are subject to tampering, they must be validated on the server. Although the durability of the cookie on a client is subject to user intervention and expiration, they are generally the most durable form of data persistence on the client.
Cookies are often used for personalization, where content is customized for a known user. Because the user is only identified and not authenticated in most cases, you can typically secure a cookie by storing the user name, account name, or a unique user ID (such as a GUID) in the cookie. You can then use the cookie to access the user personalization infrastructure of a site.
HttpContext.Items
The Items collection is a good location to store data that is needed only while processing one particular request. The collection's contents are discarded after each request. The Items collection is best used as a way for components or middleware to communicate when they operate at different points in time during a request and have no direct way to pass parameters. For more information, see Working with HttpContext.Items, later in this article.
Cache
Caching is an efficient way to store and retrieve data. You can control the lifetime of cached items based on time and other considerations. Learn more about Caching.
Configuring Session
The Microsoft.AspNetCore.Session package provides middleware for managing session state. To enable the session middleware, Startupmust contain:
- Any of the IDistributedCache memory caches. The
IDistributedCacheimplementation is used as a backing store for session. - AddSession call, which requires NuGet package "Microsoft.AspNetCore.Session".
- UseSession call.
The following code shows how to set up the in-memory session provider.
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using System;
public class Startup
{
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Adds a default in-memory implementation of IDistributedCache.
services.AddDistributedMemoryCache();
services.AddSession(options =>
{
// Set a short timeout for easy testing.
options.IdleTimeout = TimeSpan.FromSeconds(10);
options.CookieHttpOnly = true;
});
}
public void Configure(IApplicationBuilder app)
{
app.UseSession();
app.UseMvcWithDefaultRoute();
}
}
You can reference Session from HttpContext once it is installed and configured.
If you try to access Session before UseSession has been called, the exception InvalidOperationException: Session has not been configured for this application or request is thrown.
If you try to create a new Session (that is, no session cookie has been created) after you have already begun writing to the Response stream, the exception InvalidOperationException: The session cannot be established after the response has started is thrown. The exception can be found in the web server log; it will not be displayed in the browser.
Loading Session asynchronously
The default session provider in ASP.NET Core loads the session record from the underlying IDistributedCache store asynchronously only if the ISession.LoadAsync method is explicitly called before the TryGetValue, Set, or Remove methods. If LoadAsync is not called first, the underlying session record is loaded synchronously, which could potentially impact the ability of the app to scale.
To have applications enforce this pattern, wrap the DistributedSessionStore and DistributedSession implementations with versions that throw an exception if the LoadAsync method is not called before TryGetValue, Set, or Remove. Register the wrapped versions in the services container.
Implementation Details
Session uses a cookie to track and identify requests from a single browser. By default, this cookie is named ".AspNet.Session", and it uses a path of "/". Because the cookie default does not specify a domain, it is not made available to the client-side script on the page (because CookieHttpOnly defaults to true).
To override session defaults, use SessionOptions:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
// Adds a default in-memory implementation of IDistributedCache.
services.AddDistributedMemoryCache();
services.AddSession(options =>
{
options.CookieName = ".AdventureWorks.Session";
options.IdleTimeout = TimeSpan.FromSeconds(10);
});
}
The server uses the IdleTimeout property to determine how long a session can be idle before its contents are abandoned. This property is independent of the cookie expiration. Each request that passes through the Session middleware (read from or written to) resets the timeout.
Because Session is non-locking, if two requests both attempt to modify the contents of session, the last one overrides the first. Session is implemented as a coherent session, which means that all the contents are stored together. Two requests that are modifying different parts of the session (different keys) might still impact each other.
Setting and getting Session values
Session is accessed through the Session property on HttpContext. This property is an ISession implementation.
The following example shows setting and getting an int and a string:
public class HomeController : Controller
{
const string SessionKeyName = "_Name";
const string SessionKeyYearsMember = "_YearsMember";
const string SessionKeyDate = "_Date";
public IActionResult Index()
{
// Requires using Microsoft.AspNetCore.Http;
HttpContext.Session.SetString(SessionKeyName, "Rick");
HttpContext.Session.SetInt32(SessionKeyYearsMember, 3);
return RedirectToAction("SessionNameYears");
}
public IActionResult SessionNameYears()
{
var name = HttpContext.Session.GetString(SessionKeyName);
var yearsMember = HttpContext.Session.GetInt32(SessionKeyYearsMember);
return Content($"Name: \"{name}\", Membership years: \"{yearsMember}\"");
}
If you add the following extension methods, you can set and get serializable objects to Session:
using Microsoft.AspNetCore.Http;
using Newtonsoft.Json;
public static class SessionExtensions
{
public static void Set<T>(this ISession session, string key, T value)
{
session.SetString(key, JsonConvert.SerializeObject(value));
}
public static T Get<T>(this ISession session,string key)
{
var value = session.GetString(key);
return value == null ? default(T) :
JsonConvert.DeserializeObject<T>(value);
}
}
The following sample shows how to set and get a serializable object:
public IActionResult SetDate()
{
// Requires you add the Set extension method mentioned in the article.
HttpContext.Session.Set<DateTime>(SessionKeyDate, DateTime.Now);
return RedirectToAction("GetDate");
}
public IActionResult GetDate()
{
// Requires you add the Get extension method mentioned in the article.
var date = HttpContext.Session.Get<DateTime>(SessionKeyDate);
var sessionTime = date.TimeOfDay.ToString();
var currentTime = DateTime.Now.TimeOfDay.ToString();
return Content($"Current time: {currentTime} - "
+ $"session time: {sessionTime}");
}
Working with HttpContext.Items
The HttpContext abstraction provides support for a dictionary collection of type IDictionary<object, object>, called Items. This collection is available from the start of an HttpRequest and is discarded at the end of each request. You can access it by assigning a value to a keyed entry, or by requesting the value for a particular key.
In the sample below, Middleware adds isVerified to the Items collection.
app.Use(async (context, next) =>
{
// perform some verification
context.Items["isVerified"] = true;
await next.Invoke();
});
Later in the pipeline, another middleware could access it:
app.Run(async (context) =>
{
await context.Response.WriteAsync("Verified request? " +
context.Items["isVerified"]);
});
For middleware that will only be used by a single app, string keys are acceptable. However, middleware that will be shared between applications should use unique object keys to avoid any chance of key collisions. If you are developing middleware that must work across multiple applications, use a unique object key defined in your middleware class as shown below:
public class SampleMiddleware
{
public static readonly object SampleKey = new Object();
public async Task Invoke(HttpContext httpContext)
{
httpContext.Items[SampleKey] = "some value";
// additional code omitted
}
}
Other code can access the value stored in HttpContext.Items using the key exposed by the middleware class:
public class HomeController : Controller
{
public IActionResult Index()
{
string value = HttpContext.Items[SampleMiddleware.SampleKey];
}
}
This approach also has the advantage of eliminating repetition of "magic strings" in multiple places in the code.
Application state data
Use Dependency Injection to make data available to all users:
- Define a service containing the data (for example, a class named
MyAppData).
public class MyAppData
{
// Declare properties/methods/etc.
}
- Add the service class to
ConfigureServices(for exampleservices.AddSingleton<MyAppData>();). - Consume the data service class in each controller:
public class MyController : Controller
{
public MyController(MyAppData myService)
{
// Do something with the service (read some data from it,
// store it in a private field/property, etc.)
}
}
Common errors when working with session
"Unable to resolve service for type 'Microsoft.Extensions.Caching.Distributed.IDistributedCache' while attempting to activate 'Microsoft.AspNetCore.Session.DistributedSessionStore'."
This is usually caused by failing to configure at least one
IDistributedCacheimplementation. For more information, see Working with a Distributed Cache and In memory caching.