sessionState Element (ASP.NET Settings Schema)

.NET Framework General Reference

Configures session state settings for the current application.

<sessionState 
    mode="[Off|InProc|StateServer|SQLServer|Custom]"
    timeout="number of minutes"
    cookieName="session identifier cookie name"
    cookieless=
         "[true|false|AutoDetect|UseCookies|UseUri|UseDeviceProfile]"
    regenerateExpiredSessionId="[True|False]"
    sqlConnectionString="sql connection string"
    sqlCommandTimeout="number of seconds"
    allowCustomSqlDatabase="[True|False]"
    useHostingIdentity="[True|False]"
    stateConnectionString="tcpip=server:port"
    stateNetworkTimeout="number of seconds"
    customProvider="custom provider name">
    <providers>...</providers>
</sessionState>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

Attribute

Description

allowCustomSqlDatabase

Optional Boolean attribute.

Specifies whether the session-state SQL database can be a custom database instead of the ASP.NET default database. If false, you cannot specify an initial catalog nor a database as the value for the sqlConnectionString attribute. The default session-state SQL database is the ASPState database. For more information, seeSession-State Modes.

This attribute is new in the .NET Framework version 2.0.

The default is false.

cookieless

Optional HttpCookieMode attribute.

Specifies how cookies are used for a Web application.

The cookieless attribute can be one of the following possible values. The default is the UseCookies value.

Value	Description
AutoDetect	ASP.NET determines whether the requesting browser or device supports cookies. If the requesting browser or device supports cookies, AutoDetect uses cookies to persist user data; otherwise, an identifier is used in the query string. If the browser or device supports cookies, but cookies are currently disabled, cookies are still used by the requesting feature.
UseCookies	Cookies persist user data, regardless of whether the browser or device supports cookies.
UseDeviceProfile	ASP.NET determines whether to use cookies based on the HttpBrowserCapabilities setting. If the HttpBrowserCapabilities setting indicates that the browser or device supports cookies, cookies are used; otherwise, an identifier is used in the query string.
UseUri	The calling feature uses the query string to store an identifier, regardless of whether the browser or device supports cookies.

cookieName

Optional String attribute.

Specifies the name of the cookie that stores the session identifier.

This attribute is new in the .NET Framework version 2.0.

The default is "ASP.NET_SessionId".

customProvider

Optional String attribute.

Specifies the name of a custom session-state provider to use for storing and retrieving session-state data. The provider is specified in the providers element. The provider is used only when the session-state mode is set to the Custom value. For more information, see Session-State Modes.

This attribute is new in the .NET Framework version 2.0.

The default is an empty string ("").

mode

Optional SessionStateMode attribute.

Specifies where to store session state values. For more information, see Session-State Modes.

The mode attribute can be one of the following possible values. The default is the InProc value.

Value	Description
Custom	Session state is using a custom data store to store session-state information.
InProc	Session state is in process with an ASP.NET worker process.
Off	Session state is disabled.
SQLServer	Session state is using an out-of-process SQL Server database to store state information.
StateServer	Session state is using the out-of-process ASP.NET state service to store state information.

partitionResolverType

Optional String attribute.

Specifies where to store the session state. If a value is specified in the partitionResolverType attribute, the sqlConnectionString and stateConnectionString attributes are ignored. The connection string that is returned by the PartitionResolverType property is used on each request to connect to the appropriate server location for the remainder of the request. If the connection string is not valid, ASP.NET throws the same exception that is thrown when the configured connection string to the server is not valid. This property is used to partition session-state data across multiple backend nodes when in SQL or state-server mode.

This attribute is new in the .NET Framework version 2.0.

The default is an empty string.

regenerateExpiredSessionId

Optional Boolean attribute.

Specifies whether the session ID will be reissued when an expired session ID is specified by the client. By default, session IDs are reissued only for the cookieless mode when regenerateExpiredSessionId is enabled. For more information, see IsCookieless.

This attribute is new in the .NET Framework version 2.0.

The default is true.

sqlCommandTimeout

Optional TimeSpan attribute.

Specifies the duration time-out, in seconds, for the SQL commands that are using the SQL Server session-state mode. The duration time-out is the number of seconds a SQL command can be idle before it is canceled.

This attribute is new in the .NET Framework version 2.0.

The default is 0:00:30 (30 seconds).

sqlConnectionString

Optional String attribute.

Specifies the connection string for a computer running SQL Server. This attribute is required when the mode attribute is set to the SQLServer value. For more information, see Session-State Modes.

You can either set this attribute to a named sqlConnectionString from the <connectionStrings> node or use the following syntax:

sqlConnectionString="Data Source=.\SQLServer2005;Initial Catalog=SessionState;Integrated Security=SSPI;"

Note
To improve the security of your application when you are using SQLServer mode, use Protected Configuration to help protect the sqlConnectionString value by encrypting the sessionState section of your configuration.

The default is "data source=127.0.0.1;Integrated Security=SSPI".

stateConnectionString

Optional String attribute.

Specifies the server name or address and port where session state is remotely stored. The port value must be 42424. This attribute is required when mode is the StateServer value. Make sure that the ASP.NET state service is running on the remote server that stores the session-state information. This service is installed with ASP.NET, and by default is located in %windir%\Microsoft.NET\Framework\VersionNumber\aspnet_state.exe. For more information, see Session-State Modes.

Note
To improve the security of your application when using StateServer mode, use Protected Configuration to help protect the stateConnectionString value by encrypting the <sessionState>section of your configuration.

The default is "tcpip=127.0.0.1:42424".

stateNetworkTimeout

Optional TimeSpan attribute.

Specifies the number of seconds that the TCP/IP network connection between the Web server and the state server can be idle before the request is canceled. This attribute is used when the mode attribute is set to the StateServer value.

The default is 10 seconds.

timeout

Optional TimeSpan attribute.

Specifies the number of minutes a session can be idle before it is abandoned. The timeout attribute cannot be set to a value that is greater than 525,601 minutes (1 year) for the in-process and state-server modes.

The session timeout configuration setting applies only to ASP.NET pages. Changing the session timeout value does not affect the session time-out for ASP pages. Similarly, changing the session time-out for ASP pages does not affect the session time-out for ASP.NET pages.

The default is 20 minutes.

useHostingIdentity

Optional Boolean attribute.

Specifies whether the session state will revert to the hosting identity or use client impersonation.

If true, ASP.NET connects to the session-state store using one of the following process credentials:

The hosting process, which is ASPNET for Microsoft Internet Information Services (IIS) versions 5 and 5.1 or NETWORK SERVICE for Microsoft Windows Server 2003.
The application impersonation identity, which is when the following configuration is used:

<identity impersonate="true" userName="domain\username" password="********" />

If false, ASP.NET connects to the session-state store using the credentials that are currently associated with the operating system thread for the current request. For client impersonation, ASP.NET will connect to the session-state store using the security credentials that were negotiated with the browser. If false, ASP.NET does not revert to the process identity or the application impersonation identity when connecting to the session-state store. For more information, see ASP.NET Impersonation.

This attribute is new in the .NET Framework version 2.0.

The default is true.

Note
In the .NET Framework version 1.1, if the mode attribute was set to SQLServer, and client impersonation was in effect, ASP.NET connected to the computer running SQL Server using the client credentials from the ASP.NET client impersonation.

Inherited attributes

Optional attributes.

Attributes inherited by all section elements.

Child Elements

Element	Description
providers	Contains a collection of custom session-state store providers.

Parent Elements

Element	Description
configuration	The required root element in every configuration file that is used by the common language runtime and the .NET Framework–based applications.
system.web	Specifies the root element for the ASP.NET configuration settings in a configuration file and contains elements that configure ASP.NET Web applications and control how the applications behave.

Remarks

The <sessionState> element configures session-state settings for the current application.

When a new client begins interacting with a Web application, a session ID is issued and associated with all the subsequent requests from the same client while the session is valid. This ID is used to maintain the server-side state that is associated with the client session across requests. The <sessionState> element controls how the ASP.NET application establishes and maintains this association for each client.

This mechanism is very flexible and lets you host session-state information out of process and track state without using cookies, among other things.

You can exceed the maximum size of the URI when you send the session ID in the URI. If the combination of the anonymous identification ticket, forms authentication ticket, session ID, and user data is greater than the maximum permissible URI length, the request will fail with a 400-Bad Request error.

To use StateServer mode

On the remote server that will store session-state information, make sure that the ASP.NET state service is running.

The ASP.NET state service is installed with ASP.NET, and by default is located in %windir%\Microsoft.NET\Framework\version\aspnet_state.exe.
In the Web.config file for the application, set mode to "StateServer" and stateConnectionString to a value, such as "tcpip=dataserver:42424".

To use SQLServer mode

On the computer running SQL Server that will store the session state, run InstallSqlState.sql.

By default, InstallSqlState.sql is in %windir%\Microsoft.NET\Framework\version.

This creates a database named ASPState with new stored procedures and tables named ASPStateTempApplications and ASPStateTempSessions in the TempDB database.
In the Web.config file for the application, set mode to "SQLServer" and sqlConnectionString to a value, such as "data source=localhost;Integrated Security=SSPI;".

Note

You can use Aspnet_regsql.exe to complete these steps.

Note
You can use Aspnet_regsql.exe to complete these steps.

For information about accessing and modifying configuration values for the <sessionState> element in application code, see SessionStateSection and System.Web.SessionState.

Default Configuration

The following default <sessionState> element is not explicitly configured in the Machine.config file or in the root Web.config file. However, it is the default configuration that is returned by the application.

<sessionState 
   mode="InProc" 
   stateConnectionString="tcpip=127.0.0.1:42424" 
   stateNetworkTimeout="10" 
   sqlConnectionString="data source=127.0.0.1;Integrated Security=SSPI" 
   sqlCommandTimeout="30" 
   customProvider="" 
   cookieless="UseCookies" 
   cookieName="ASP.NET_SessionId" 
   timeout="20" 
   allowCustomSqlDatabase="false" 
   regenerateExpiredSessionId="true" 
   partitionResolverType="" 
   useHostingIdentity="true">
   <providers>
      <clear />
   </providers>
</sessionState>

Example

The following example demonstrates how to specify session state configuration settings.

<sessionState
   mode="SQLServer"
   cookieless="true"
   sqlConnectionString=" Integrated Security=SSPI;data source=MySqlServer;"
   sqlCommandTimeout="10" />

Element Information

Configuration section handler	SessionStateSection
Configuration member	System.Web.SessionState
Configurable locations	Machine.config Root-level Web.config Application-level Web.config
Requirements	Microsoft Internet Information Services versions 5.0, 5.1, or 6.0 The .NET Framework versions 1.0, 1.1, or 2.0 Microsoft Visual Studio 2003 or Visual Studio 2005

Attributes

Child Elements

Parent Elements

Tasks

Reference

Concepts

Other Resources