ASP.NET.in.a.Nutshell.Second.Edition [Electronic resources] نسخه متنی

19.2 Properties Reference

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.