sessionState Element (ASP.NET Settings Schema)
Configures session state settings for the current application.
configuration Element (General Settings Schema)
system.web Element (ASP.NET Settings Schema)
sessionState Element (ASP.NET Settings Schema)
<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]"
sessionIDManagerType="session manager type"
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"
compressionEnabled="[True|False]"
sqlConnectionRetryInterval="number of seconds">
<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. |
compressionEnabled |
Optional Boolean attribute. Specifies whether compression is applied to the session-state data. 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. Note When you configure an AJAX-enabled ASP.NET Web site, use only the default value of UseCookies for the cookieless attribute. Settings that use cookies encoded in the URL are not supported by the ASP.NET AJAX client script libraries.
ValueDescription
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.
ValueDescription
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. |
sessionIDManagerType |
Optional String attribute. Specifies the fully qualified type of the session ID Manager. The default value is an empty string. |
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). |
sqlConnectionRetryInterval |
Optional TimeSpan attribute. Specifies the time interval, in seconds, between attempts to connect to the database. The default is 0 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: Note To improve the security of your application when you are using SQLServer mode, useProtected 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, useProtected Configuration to help protect the stateConnectionString value by encrypting the sessionStatesection of the 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,600 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:
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.
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 |
|
Configuration member |
|
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 |
See Also
Tasks
How to: Configure Specific Directories Using Location Settings
How to: Lock ASP.NET Configuration Settings
Reference
system.web Element (ASP.NET Settings Schema)
providers Element for sessionState (ASP.NET Settings Schema)
configuration Element (General Settings Schema)
Concepts
ASP.NET Configuration File Hierarchy and Inheritance
Securing ASP.NET Configuration
ASP.NET Configuration Scenarios
Other Resources
Encrypting Configuration Information Using Protected Configuration
General Configuration Settings (ASP.NET)
ASP.NET Configuration Settings