13.4 Methods Reference

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

Adds a value to the Application collection.

Parameter

name

A variable of type String that specifies the name of the item to be added to the Application collection.

value

A variable of type Object that contains the value for the item to be added to the Application collection.

Example

The example adds an item to the Application collection and then displays it:

Sub Page_Load( )
   Application.Add("Added", "AddedValue")
   Message.Text = Application("Added")
End Sub

Notes

The Add method, which is new in ASP.NET, provides a technique for adding items to the Application collection that is consistent with the technique used for adding items to other .NET collections. Of course, the classic ASP syntax of directly indexing the Application object by using the key name of index works correctly as well.

Application.Clear( )

Clears the contents of the Application collection.

Parameters

None.

Example

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

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

Notes

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

Application.Get(ByVal name As String)
Application.Get(ByVal Index As Integer)

Gets an element of the Application collection either by name or ordinal position (index) within the Application collection. Generally, the name is used in calls to Get unless you need to get members of the collection inside a loop.

Parameters

name

A variable of type String that specifies the name of the item to be retrieved from the Application collection.

Index

A variable of type Integer that specifies the index of the item to be retrieved from the Application collection.

Example

The example below sets and gets a value from the Application collection. It also uses the Get method to write a message to the Text property of the Message control that includes the current value of the newly added element of the Application collection.

Sub Page_Load( )
   Application("GetTest") = "Got it!"
   Message.Text = "GetTest = " & Application.Get("GetTest")
End Sub

Notes

You can see whether a named value is saved in the Application collection by checking to ensure that its value is not null, as shown in the following code:

If Not Application("Foo") is Nothing then
   Message.Text = "Foo is set to " & Application.Get("Foo")
End If

Application.GetKey(ByVal Index As Integer)

Retrieves the key name corresponding to the index of a data item stored to the Application object.

Parameter

Index

A variable of type Integer that specifies the index of the key to be retrieved from the Application collection.

Example

The example removes all values from the Application collection in order to start from a known state. Next, it writes a single value to the Application collection. Finally, it saves the key from the first element (index 0) retrieved by a call to GetKey into the Message control.

Sub Page_Load( )
   Application.RemoveAll( )
   Application("GetKeyTest") = "Got it!"
   Message.Text = "Key of Application(0) = " & _ 
                   Application.GetKey(0) & _
                   "<br/>(Should be GetKeyTest)"
End Sub

Notes

If Index is less than 0 or greater than Application.Count - 1, an ArgumentOutOfRangeException exception will be thrown.

Application.Lock

Locks access to an Application collection to facilitate access synchronization.

Parameters

None.

Example

The example locks the application, sets an application page load counter variable, unlocks the application, and displays the value:

Sub Page_Load( )
   Application.Lock( )
   Application("Counter") = Application("Counter") + 1
   Application.UnLock( )
   Message.Text = "Counter = " & Application("Counter") 
End Sub

Notes

In the example, note that we Lock the application, perform any operations that modify values within the Application collection, and UnLock the application as quickly as possible. Any read access to the Application collection can safely take place outside the Lock/UnLock method calls.

Application.Remove(ByVal name As String)

Removes an item by name from the Application collection.

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 Application collection and, if it does, removes the item and displays an appropriate message:

Sub Page_Load( )
   If Not Application("foo") Is Nothing Then
      Application.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 backwards 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.

Application.RemoveAll( )

Removes all items from the Application collection.

Parameters

None.

Example

The example checks to ensure that at least one item is in the Application collection, and if it is, it clears the collection by calling the RemoveAll method.

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

Notes

The RemoveAll method is provided for backwards 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.

Application.RemoveAt(ByVal index As Integer)

Removes an item from the Application 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 Application collection.

Example

Sub Page_Load( )
   If Application.Count > 0 Then
      Application.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 Application 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 then call RemoveAt again with the same index, you will remove the item that immediately followed the original removed item. If a single item is in the Application collection and you call RemoveAt a second time, an ArgumentOutOfRangeException exception will be thrown.

Application.Set(ByVal name As String, ByVal value As Object)

Updates the value of an object in the Application collection. This new method allows you to set objects in the Application collection.

Parameters

Name

A String argument containing the name of the object in the Application collection to be updated.

Value

An Object argument containing the new value of the Application collection object to be updated.

Example

The example uses Set twice—once to set a new item in the Application collection and again to change that value.

Sub Page_Load( )
   Application.RemoveAll( )
   Application.Set("TotallyNewVariable","Test!")
   Message.Text = "First: " + Application("TotallyNewVariable") + "<br/>"
   Application.Set("TotallyNewVariable","Test again!")
   Message.Text = Message.Text & "First after Set: " +     
   Application("TotallyNewVariable") + "<br/>"
End Sub

Notes

Set can be used to add values to the Application collection, but you will normally just use the simple syntax you are used to from classic ASP:

    Application("TotallyNewVariable") = "Test!"

Application.UnLock

Unlocks access to an Application collection to facilitate access synchronization.

Parameters

None.

Example

The example locks the application, sets an application page load counter variable, unlocks the application, and displays the value:

Sub Page_Load( )
   Application.Lock( )
   Application("Counter") = Application("Counter") + 1
   Application.UnLock( )
   Message.Text = "Counter = " & Application("Counter") 
End Sub

Notes

In the example, note that we Lock the application, perform any operations that modify values within the Application collection, and UnLock the application as quickly as possible. Any read access to the Application collection can safely take place outside the Lock/UnLock method calls.