19.2 Properties Reference | ASP.NET in a Nutshell, Second Edition

CodePage

Integer = Session.CodePage Session.CodePage = Integer

Returns or sets an integer indicating the code page to be used in generating the page output. The code page is the character set that contains all characters and punctuation for a given locale setting.

Parameter

Integer: An Integer variable that will receive or set the code page property value.

Example

The example writes the current code page value to the Text property of the Message label control:

Sub Page_Load( )    Message.Text = "Current Code Page is: " & Session.CodePage End Sub

Notes

The CodePage property is provided for compatibility with classic ASP. For new ASP.NET development, you should use the ContentEncoding property of the Response class for formatting output to a given code page, or configure globalization settings in web.config (see Chapter 8 and Chapter 20 for more information on globalization settings).

In the example above, although the property value is an Integer, ASP.NET automatically casts the Integer value to a String, which is then assigned to the Text property. This works because any .NET object or data type can be represented as a String.

Count

Integer = Session.Count

Returns an integer containing the number of items currently in the Session collection.

Parameter

Integer: An Integer variable that will receive the count property value.

Example

The example adds two values to the Session collection, displays the count of the items in the Session collection, and then displays each item, using the Count property as a looping control value:

Sub Page_Load( )    Session("foo") = "Hello, "    Session("bar") = "World!"    Message.Text = "The Session collection contains " & _          Session.Count & " items.</br>"       Dim I as Integer       For I = 0 To Session.Count - 1          Message.Text &= CStr(Session(I)) & "</br>"       Next End Sub

Notes

The Count property is new for ASP.NET. In addition to using the Count property for looping through the Session collection, you can use the property to keep track of how many items a given Session stores at any given time. For example, you could write this information to a log for later review.

IsCookieless

Boolean = Session.IsCookieless

Returns a Boolean indicating whether the application is configured for cookieless Session operation.

Parameter

Boolean: A Boolean variable that will receive the IsCookieless property value.

Example

The example displays a message indicating whether cookieless sessions have been enabled for the current session:

Sub Page_Load( )    If Session.IsCookieless Then       Message.Text = "The current Session does not use cookies."    Else       Message.Text = "The current Session uses cookies."    End If End Sub

Notes

The IsCookieless property is new for ASP.NET, and is especially useful in combination with the Response.ApplyAppPathModifier method, which allows you to create absolute URLs containing the current SessionID for use with cookieless sessions.

IsNewSession

Boolean = Session.IsNewSession

Returns a Boolean indicating whether the current session was created as a result of the current request.

Parameter

Boolean: A Boolean variable that will receive the IsNewSession property value. Returns True on the request that creates a Session and False for each subsequent request from the same client.

Example

The example tests to see if the current request created a new session and if so, adds a value to the Session collection and then displays a message containing the SessionID of the current session:

Sub Page_Load( )    If Session.IsNewSession Then       Session("foo") = "foo"       Message.Text = "The current Session (SessionID: " & _          Session.SessionID & ") was created with this request."    Else       Message.Text = "The current Session (SessionID: " & _          Session.SessionID & ") existed prior to this request."    End If End Sub

Notes

The IsNewSession property is very useful when you want to initialize Session collection items for only certain pages. Unlike the Session_OnStart event handler in global.asax, which is called when a session is created, regardless of which page creates the session, this property gives you finer-grained control over initialization and session behavior.

As mentioned in the introduction to this chapter, while a new SessionID is generated for each request that does not already have a session, a new session is not created for a given request unless the requested page stores a value in the Session collection or an event handler exists in global.asax for the Session Start event.

Thus, if you commented out the line:

Session("foo") = "foo"

in the example above, and no Session_OnStart event handler was defined in global.asax, each request to the page would result in a new SessionID being generated, but no session would actually be created by the request.

IsReadOnly

Boolean = Session.IsReadOnly

Returns a Boolean indicating whether the current session can be written to from the current page. This property is set to True when the EnableSessionState attribute of the @ Page directive is set to ReadOnly.

Parameter

Boolean: A Boolean variable that will receive the IsReadOnly property value. The default is False.

Example

The example tests whether the session is set to ReadOnly for the page and if so, displays an appropriate message. If not, it writes a value to the Session collection and then displays a different message:

Sub Page_Load( )    If Session.IsReadOnly Then       Message.Text = "The current Session (SessionID: " & _          Session.SessionID & ") is read-only for this page."    Else       Session("foo") = "foo"       Message.Text = "The current Session (SessionID: " & _          Session.SessionID & ") can be written to from this page."    End If End Sub

To test this page, add the EnableSessionState attribute to the @ Page directive for the page, setting its value to ReadOnly, as shown here:

<%@ Page Language="vb" EnableSessionState="ReadOnly" %>

Notes

Read-only session state is new in ASP.NET and is designed to improve the efficiency of pages that require only read access to the Session collection. Attempting to write to the Session collection from a page with the EnableSessionState attribute set to ReadOnly will result in an exception being thrown.

Item

Object = Session.Item(ByVal name As String) Session.Item(ByVal name As String) = Object Object = Session.Item(ByVal index As Integer) Session.Item(ByVal index As Integer) = Object

Returns or sets an object associated with a particular name or index.

Parameters

Object: A variable of any type (since all .NET types are ultimately derived from Object) that will receive or set the item's value.
name: A string argument containing the text key to apply to the item or by which to retrieve the item.
index: An integer argument containing the index of the item whose value will be retrieved or modified.

Example

The example sets the values of two items in the Session collection. If these items do not already exist in the collection, they will be added. The example then displays the two values:

Sub Page_Load( )    Session.Item("foo") = "foo"    Session.Item("foo2") = "foo2"    Message.Text = CStr(Session.Item("foo")) & "</br>"    Message.Text &= CStr(Session.Item(1)) End Sub

Notes

The Item property is accessed implicitly when using the syntax:

Session("foo") = "foo"

which is commonly seen in classic ASP code. Using the Item property is not required, but it may make your code more readable and understandable than accessing it implicitly.

Note that an index may be used only as an argument when modifying a value, not to create a new item. The index must also be smaller than the number of items in the Session collection or an exception will be thrown.

LCID

Integer = Session.LCID Session.LCID = Integer

Returns or sets an integer containing the locale identifier for the session. The locale identifier determines how information such as date/time values is formatted.

Parameter

Integer: An integer variable that will receive or set the LCID property value.

Example

The example displays the current LCID value and displays the current date and time formatted based on the current LCID. It then changes the LCID to the value for French, displays the LCID value, and displays the current date and time again, this time formatted based on the new LCID:

Sub Page_Load( )    Message.Text = "Current locale ID is: " & Session.LCID & "</br>"    Message.Text &= "Current date and time is: " & DateTime.Now( ) & "</br>"    Session.LCID = 1036 'France    Message.Text &= "Current locale ID is: " & Session.LCID & "</br>"    Message.Text &= "Current date and time is: " & DateTime.Now( ) & "</br>" End Sub

Notes

The LCID property is provided for backward compatibility with classic ASP. For new ASP.NET development, you should use the System.Threading.CurrentThread.CurrentCulture.LCID property instead. ASP.NET stores and retrieves the Session.LCID property in System.Threading.CurrentThread.CurrentCulture.LCID.

Mode

SessionStateMode = Session.Mode

Returns one of the values of the SessionStateMode enumeration that describes the mode for which session state for the application has been configured.

Parameter

SessionStateMode

One of the following members of the SessionStateMode enumeration:

InProc: Indicates that session state is stored in-process. This setting provides the best performance when using session state storage, but cannot be shared across multiple servers.
Off: Indicates that session state is disabled. This setting provides the best performance overall, but at the expense of not using session state storage.
SQLServer: Indicates that session state is stored out-of-process in a SQL Server database. This setting allows state sharing across machines at the expense of some performance.
StateServer: Indicates that session state is stored out of process in a special NT service. This setting also allows state sharing across machines at the expense of some performance.

Example

The example writes a message containing the current Session state mode to the Text property of the Message ASP.NET Label control. To get the string representation of the enumeration value, call ToString on the Mode property value as shown:

Sub Page_Load( )    Message.Text = "The current Session state mode is: " & _       Session.Mode.ToString( ) & ".</br>" End Sub

Notes

The Mode property allows you to test the current mode of session state storage. One use for this property is to determine whether to store information in the Session collection, depending on the mode. Because both the StateServer and SQLServer modes require cross-process communication (which can be very expensive relative to in-process communication), you may wish to provide alternative means for storing certain information if one of these modes is used. Using the Mode property, you can write conditional statements that will decide at runtime whether or not to store a particular value based on the current session state mode. That way, if the session state mode is changed administratively, no change to your code is required.

SessionID

String = Session.SessionID

Returns a string containing the unique identifier for the current session.

Parameters

String: A string variable that will receive the session ID property value.

Example

See the example for the IsReadOnly property.

Notes

The SessionID property value is generated the first time a page for which session state has not been disabled is requested. As noted earlier, the actual session is not created unless either an event handler is provided in global.asax for the Session.Start event or a value is stored in the Session collection. The SessionID is stored on the client in a nonpersistent cookie, or if cookieless sessions are enabled, is passed as part of each URL request.

Note that if the client's browser is closed, the client will be unable to access their session (since the nonpersistent cookie will be destroyed when the browser is closed), but the session will continue to exist on the server until the configured timeout period has elapsed. If you want to explicitly expire a session, you can check the IsClientConnected property of the HttpResponse class, which returns a Boolean indicating whether the client has disconnected. If it returns False, you can then call Session.Abandon to expire the session.

While the SessionID value, which is a 120-bit ASCII string in ASP.NET, is unique to a given IIS application instance, it is not guaranteed to be universally unique and therefore should not be used for database identity values or for other purposes requiring universally unique values.

Timeout

Integer = Session.Timeout Session. Timeout = Integer

Returns or sets an integer containing the amount of time, in minutes, that can elapse between requests without the session being destroyed. If the timeout value is exceeded, the current session is destroyed and the Session.End event is fired.

Parameter

Integer: An integer variable that will receive or set the Timeout property value.

Example

The example writes the current value of the Timeout property to the Text property of the Message ASP.NET Label control:

Sub Page_Load( )    Message.Text = "Current Session timeout value is " & _       Session.Timeout & " minutes." End Sub

Notes

You can use the Timeout property to temporarily override the timeout setting configured in web.config or machine.config, if you wish to make the value more restrictive for some reason.