ASP NET in a Nutshell 2nd Edition-ASP NET in a Nutshell 2nd Edition

19.4 Methods Reference

Abandon

Session.Abandon( )

Immediately terminates the current user's session and causes the Session.End event to be fired.

Parameters

None

Example

The example examines the IsNewSession property to determine if the current request has resulted in a new session. If so, it adds a value to the Session collection and then displays a message indicating that a new session was created. If a session already exists, the example displays a button that, when clicked, causes a postback. This postback results in the Session.Abandon method being called and the session terminated:

If Not IsPostBack
   If Session.IsNewSession Then
      Session("foo") = "foo"
      Message.Text = "The current Session (SessionID: " & _
      Session.SessionID & ") was created with this request."
   Else
      Message.Text = "Click the button to abandon the current session."
      Dim AbandonButton As New Button
      AbandonButton.Text = "Abandon Session"
      myForm.Controls.Add(AbandonButton)
   End If
Else
   Session.Abandon( )
   Message.Text = "Session abandoned."
End If

In order for the postback to work correctly, a server-side form needs to be added within the <body> tags, as shown below:

<form id="myForm" runat="server">
   <asp:label id="Message" runat="server"/>
</form>

Notes

The Abandon method is very important for controlling resource usage in ASP.NET applications that use session state. If you use session state for storing application data, you should implement a logout method that calls Session.Abandon and make it as easy as possible for your users to access this method (via a button or link on each page). Implementing this method will help prevent resources from being consumed for longer than necessary when a user has already quit using the application.

Note that the End event will be fired only when session state has been configured for in-process operation.

Add

Session.Add(ByVal name As String, ByVal value As Object)

Adds an item to the Session collection.

Parameters

name: A string argument containing the name that will be used to refer to the new item.
value: An object argument containing the value of the new item.

Example

The example declares a local variable, sets its value, and adds an item to the Session collection with the value of the local variable:

Sub Page_Load( )
   Dim myBaz As String = "baz"
   Session.Add("baz", myBaz)
   Dim I as Integer
   For I = 0 To Session.Count - 1
      Message.Text &= CStr(Session(I)) & "<br/>"
   Next
End Sub

Notes

The Add method, which is new in ASP.NET, provides a technique for adding items to the Session collection, which is consistent with the technique used for adding items to other .NET collections.

Clear

Session.Clear( )

Clears the contents of the Session collection for the current user.

Parameters

None

Example

The example clears the contents of the Session collection and writes a message to the Text property of the Message label control that includes the current count of the collection, which should be 0:

Sub Page_Load( )
   Session.Clear( )
   Message.Text = "There are " & Session.Count & _
      " items in the Session collection."
End Sub

Notes

The Clear method, which is new for ASP.NET, clears only the contents of the Session collection itself. It does not clear the contents of the StaticObjects collection.

CopyTo

Session.CopyTo(ByVal array As Array, ByVal index As Integer)

Copies the contents of the Session collection to a one-dimensional array.

Parameters

array: An array argument that will receive the session collection values.
index: An integer argument specifying the point in the array at which to begin copying.

Example

The example checks to ensure that at least one item is in the Session collection, and if there is, it creates a local object array, copies the contents of the Session collection to it, and displays the value of the first item:

Sub Page_Load( )
   If Session.Count > 0 Then
      Dim myArray As Array = Array.CreateInstance(GetType(Object), _
         Session.Count)
      Session.CopyTo(myArray, 0)
      Message.Text = "The first item in the array is: " & _    
         CStr(myArray(0))
   End If
End Sub

Notes

The CopyTo method is useful if you have a large number of items stored in the Session collection. In such cases, accessing values from a local array variable may be faster and more efficient than accessing the values from the Session collection, particularly when session state is configured to run out of process. The improved efficiency and performance comes at the cost of ease of use, since arrays do not provide the same feature richness as the Session collection.

Remove

Session.Remove(ByVal name As String)

Removes an item from the Session collection by name.

Parameter

name: A string argument containing the name (key) of the item to remove.

Example

The example determines whether the item with the key "foo" exists in the Session collection and if it does, removes the item and displays an appropriate message:

Sub Page_Load( )
   If Not Session("foo") Is Nothing Then
      Session.Remove("foo")
      Message.Text = "Item 'foo' was removed."
   Else
      Message.Text = "Item 'foo' does not exist."
   End If
End Sub

Notes

The Remove method is provided for backward compatibility with classic ASP. In classic ASP, this method was accessed through the Contents collection. In ASP.NET, this method can be accessed either directly, as shown above, or through the Contents collection.

RemoveAll

Session.RemoveAll( )

Removes all items from the Session collection.

Parameters

None

Example

The example checks to ensure that at least one item is in the Session collection (although if RemoveAll is called on an empty Session collection, no error will occur), and if it is, it clears the collection by calling the RemoveAll method:

Sub Page_Load( )
   If Session.Count > 0 Then
      Session.RemoveAll( )
      Message.Text = "Session collection cleared."
   Else
      Message.Text = "Session collection is already empty."
   End If
End Sub

Notes

The RemoveAll method is provided for backward compatibility with classic ASP. In classic ASP, this method was accessed through the Contents collection. In ASP.NET, this method can be accessed either directly, as shown above, or through the Contents collection.

RemoveAll has the same effect as calling the Clear method and like Clear, it clears the contents of the Session collection, but does not remove Session-scoped objects from the StaticObjects collection.

RemoveAt

Session.RemoveAt(ByVal index As Integer)

Removes an item from the Session collection by index. This is a new companion to the Remove method, which removes an item by key.

Parameter

index: An integer argument containing the index location of the item to remove from the Session collection.

Example

Sub Page_Load( )
   If Session.Count > 0 Then
      Session.RemoveAt(0)
      Message.Text = "The item at index 0 was removed."
   Else
      Message.Text = "The item at index 0 does not exist."
   End If
End Sub

Notes

The RemoveAt method allows items to be removed from the Session collection by index rather than by key. As in the example above, the items that follow the removed item will shift one position in the collection when the item is removed. If you remove an item by index and call RemoveAt again with the same index, you will remove the item that immediately followed the original removed item.

[ Team LiB ]