When you think ASP, think...
Recent Articles
All Articles
ASP.NET Articles
ASPFAQs.com
Message Board
Related Web Technologies
User Tips!
Coding Tips

Sections:
Sample Chapters
Commonly Asked Message Board Questions
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Security
Stump the SQL Guru!
XML Info
Information:
Feedback
Author an Article
ASP ASP.NET ASP FAQs Message Board Feedback
Print this page.
Published: Friday, September 28, 2001

ASP.NET: Tips, Tutorials, and Code
Chapter 2: Common ASP.NET Code Techniques


Chapter 2: Common ASP.NET Code Techniques

by Scott Mitchell

In this chapter we will examine many topics, including the following:

Working with the many collections available in the .NET Framework

Reading and writing to the Web server's file system

Using regular expressions

Generating graphs and custom images on-the-fly through an ASP.NET Web page

Sending email through an ASP.NET Web page

Grabbing HTML content from another Web site through an ASP.NET Web page

Performing advanced networking features

Uploading files from the client's browser to the Web server

Retrieving low-level system information about the ASP.NET engine

Reading and writing to the Windows Event Log through an ASP.NET Web page

Reading and displaying various Windows performance counters through an ASP.NET Web page

One of the things that I personally found frustrating with classic ASP was the difficulty associated with completing many common Web-related tasks. For example, the need to allow Web visitors to upload files to the Web server is fairly common for Web developers; however, with classic ASP the only way to accomplish this without much difficulty was through the use of a third-party COM component. Similarly, common tasks such as sending emails, reading and writing to the Windows Event Log, working with the Web server's file system, and dynamically generating images based on database information were all tricky, if not impossible, without the aid of a COM component.

Thankfully this has all changed with ASP.NET. Now Web developers can easily accomplish a plethora of common tasks without the need to create or buy a third-party component thanks in large part to ASP.NET being part of the robust .NET Framework. When you install the ASP.NET software on your computer from the CD accompanying this book, in addition to the ASP.NET engine, the entire .NET Framework will be installed. The .NET Framework consists of hundreds of classes broken down into a number of logical namespaces. These classes provide the methods and properties needed to create powerful Windows applications, from standalone desktop apps to Internet applications.

ASP.NET Web pages can utilize any of these hundreds of classes, giving ASP.NET Web pages the power and flexibility that classic ASP developers could only receive with the use of bulky COM components. In this chapter we will examine many of the new features that were difficult to implement with classic ASP but can be easily performed with an ASP.NET Web page.

1. Using Collections

Most modern programming languages provide support for some type of object that can hold a variable number of elements. These objects are referred to as collections, and they can have elements added and removed with ease without having to worry about proper memory allocation. If you've programmed with classic ASP before, you're probably familiar with the Scripting.Dictionary object, a collection object that references each element with a textual key. A collection that stores objects in this fashion is known as a hash table.

There are many types of collections in addition to the hash table. Each type of collection is similar in purpose: It serves as a means to store a varying number of elements, providing an easy way, at a minimum, to add and remove elements. Each different type of collection is unique in its method of storing, retrieving, and referencing its various elements.

The .NET Framework provides a number of collection types for the developer to use. In fact, an entire namespace, System.Collections, is dedicated to collection types and helper classes. Each of these collection types can store elements of type Object. Because in .NET all primitive data types—string, integers, date/times, arrays, and so on—are derived from the Object class, these collections can literally store anything! For example, you could use a single collection to store a couple of integers, an instance of a classic COM component, a string, a date/time, and two instances of a custom-written .NET component. Most of the examples in this section use collections to house primitive data types (strings, integers, doubles). However, Listing 2.1.8 (which appears in the "Similarities Among the Collection Types" section) illustrates a collection of collections—that is, a collection type that stores entire collections as each of its elements!

Throughout this section we'll examine five collections the .NET Framework offers developers: the ArrayList, the Hashtable, the SortedList, the Queue, and the Stack. As you study each of these collections, realize that they all have many similarities. For example, each type of collection can be iterated through element-by-element using a For Each ... Next loop in VB (or a foreach loop in C#). Each collection type has a number of similarly named functions that perform the same tasks. For example, each collection type has a Clear method that removes all elements from the collection, and a Count property that returns the number of elements in the collection. In fact, the last subsection "Similarities Among the Collection Types" examines the common traits found among the collection types.

Working with the ArrayList Class

The first type of collection we'll look at is the ArrayList. With an ArrayList, each item is stored in sequential order and is indexed numerically. In our following examples, keep in mind that the developer need not worry himself with memory allocation. With the standard array, the developer cannot easily add and remove elements without concerning himself with the size and makeup of the array. With all the collections we'll examine in this chapter, this is no longer a concern.

Adding, Removing, and Indexing Elements in an ArrayList

The ArrayList class contains a number of methods for adding and removing Objects from the collection. These include Add, AddRange, Insert, Remove, RemoveAt, RemoveRange, and Clear, all of which we'll examine in Listing 2.1.1. The output is shown in Figure 2.1.

Listing 2.1.1 For Sequentially Accessed Collections, Use the ArrayList

 1: <script language="vb" runat="server">
 2:
 3:  Sub Page_Load(sender as Object, e as EventArgs)
 4:   ' Create two ArrayLists, aTerritories and aStates
 5:   Dim aTerritories as New ArrayList
 6:   Dim aStates as New ArrayList
 7:
 8:   ' Use the Add method to add the 50 states of the US
 9:   aStates.Add("Alabama")
10:   aStates.Add("Alaska")
11:   aStates.Add("Arkansas")
12:   ' ...
13:   aStates.Add("Wyoming")
14:
15:   ' Build up our list of territories, which includes
16:   ' all 50 states plus some additional countries
17:   aTerritories.AddRange(aStates) ' add all 50 states
18:   aTerritories.Add("Guam")
19:   aTerritories.Add("Puerto Rico")
20:
21:   ' We'd like the first territory to be the District of Columbia,
22:   ' so we'll explicitly add it to the beginning of the ArrayList
23:   aTerritories.Insert(0, "District of Columbia")
24:
25:   ' Display all of the territories with a for loop
26:   lblTerritories.Text = "<i>There are " & aTerritories.Count & _
27:              "territories...</i><br>"
28:
29:   Dim i as Integer
30:   For i = 0 to aTerritories.Count - 1
31:    lblTerritories.Text = lblTerritories.Text & _
32:               aTerritories(i) & "<br>"
33:   Next
34:
35:   ' We can remove objects in one of four ways:
36:   ' ... We can remove a specific item
37:   aTerritories.Remove("Wyoming")
38:
39:   ' ... We can remove an element at a specific position
40:   aTerritories.RemoveAt(0) ' will get rid of District
41:                ' of Columbia,
42:                ' the first element
43:
44:   ' Display all of the territories with foreach loop
45:   lblFewerTerritories.Text = "<i>There are now " & _
46:         aTerritories.Count & " territories...</i><br>"
47:
48:   Dim s as String
49:   For Each s in aTerritories
50:    lblFewerTerritories.Text = lblFewerTerritories.Text & _
51:                 s & "<br>"
52:   Next
53:
54:   ' ... we can remove a chunk of elements from the
55:   '   array with RemoveRange
56:   aTerritories.RemoveRange(0, 2) ' will get rid of the
57:                  ' first two elements
58:
59:   ' Display all of the territories with foreach loop
60:   lblEvenFewerTerritories.Text = "<i>There are now " & _
61:        aTerritories.Count & " territories...</i><br>"
62:
63:   For Each s in aTerritories
64:    lblEvenFewerTerritories.Text = lblEvenFewerTerritories.Text & _
65:                   s & "<br>"
66:   Next
67:
68:   ' Finally, we can clear the ENTIRE array using the clear method
69:   aTerritories.Clear()
70:  End Sub
71:
72: </script>
73:
74: <html>
75: <body>
76:  <b>The Territories of the United States:</b><br>
77:  <asp:label id="lblTerritories" runat="server" />
78:
79:  <p>
80:
81:  <b>After some working with the Territories ArrayList:</b><br>
82:  <asp:label id="lblFewerTerritories" runat="server" />
83:
84:  <p>
85:
86:  <b>After further working with the Territories ArrayList:</b><br>
87:  <asp:label id="lblEvenFewerTerritories" runat="server" />
88: </body>
89: </html>

Figure 2.1
Output of Listing 2.1.1 when viewed through a browser.

Adding Elements to an ArrayList

In Listing 2.1.1 we create two ArrayList class instances, aTerritories and aStates, on lines 5 and 6, respectively. We then populate the aStates ArrayList with a small subset of the 50 states of the United States using the Add method (lines 9 through 13). The Add method takes one parameter, the element to add to the array, which needs to be of type Object. This Object instance is then appended to the end of the ArrayList. In this example we are simply adding elements of type String to the ArrayList aStates and aTerritories.

The Add method is useful for adding one element at a time to the end of the array, but what if we want to add a number of elements to an ArrayList at once? The ArrayList class provides the AddRange method to do just this. AddRange expects a single parameter that supports the ICollection interface. A wide number of .NET Framework classes—such as the Array, ArrayList, DataView, DataSetView, and others—support this interface. On line 18 in Listing 2.1.1, we use the AddRange method to add each element of the aStates ArrayList to the end of the aTerritories ArrayList. (To add a range of elements starting at a specific index in an ArrayList, use the InsertRange method.) On lines 18 and 19, we add two more strings to the end of the aTerritories ArrayList.

Because ArrayLists are ordered sequentially, there might be times when we want to add an element to a particular position. The Insert method of the ArrayList class provides this capability, allowing the developer to add an element to a specific spot in the ArrayList collection. The Insert method takes two parameters: an integer representing the index in which you want to add the new element, and the new element, which needs to be of type Object. In line 23 we add a new string to the start of the aTerritories ArrayList. Note that if we had simply used the Add method, "District of Columbia" would have been added to the end of aTerritories. Using Insert, however, we can specify exactly where in the ArrayList this new element should reside.

Removing Elements from an ArrayList

The ArrayList class also provides a number of methods for removing elements. We can remove a specific element from an ArrayList with the Remove method. On line 37 we remove the String "Wyoming" from the aTerritories ArrayList. (If you attempt to remove an element that does not exist, an ArgumentException exception will be thrown.) Remove allows you to take out a particular element from an ArrayList; RemoveAt, used on line 40, allows the developer to remove an element at a specific position in the ArrayList.

Both Remove and RemoveAt dissect only one element from the ArrayList at a time. We can remove a chunk of elements in one fell swoop by using the RemoveRange method. This method expects two parameters: an index to start at and a count of total elements to remove. In line 56 we remove the first two elements in aTerritories with the statement: aTerritories.RemoveRange(0, 2). Finally, to remove all the contents of an ArrayList, use the Clear method (refer to Line 69 in Listing 2.1.1).

Referencing ArrayList Elements

Note that in our code example, we used two different techniques to iterate through the contents of our ArrayList. Because an ArrayList stores items sequentially, we can iterate through an ArrayList by looping from its lowest bound through its upper bound, referencing each element by its integral index. The following code snippet is taken from lines 30 through 33 in Listing 2.1.1:

For i = 0 to aTerritories.Count - 1
  lblTerritories.Text = lblTerritories.Text & _
             aTerritories(i) & "<br>"
Next

The Count property returns the number of elements in our ArrayList. We start our loop at 0 because all collections are indexed starting at 0. We can reference an ArrayList element with: aArrayListInstance(index), as we do on line 32 in Listing 2.1.1.

We can also step through the elements of any of the collection types we'll be looking at in this chapter using a For Each ... Next loop with VB.NET (or a foreach loop with C#). A simple example of this approach can be seen in the following code snippet from lines 48 through 52:

Dim s as String
For Each s in aTerritories
  lblFewerTerritories.Text = lblFewerTerritories.Text & _
               s & "<br>"
Next

This method is useful for stepping through all the elements in a collection. In the future section "Similarities Among the Collection Types," we'll examine a third way to step through each element of a collection: using an enumerator.

If we wanted to grab a specific element from an ArrayList, it would make sense to reference it in the aArrayListInstance(index) format. If, however, you are looking for a particular element in the ArrayList, you can use the IndexOf method to quickly find its index. For example,

Dim iPos as Integer
iPos = aTerritories.IndexOf("Illinois")

would set iPos to the location of Illinois in the ArrayList aTerritories. (If Illinois did not exist in aTerritories, iPos would be set to -1.) Two other forms of IndexOf can be used to specify a range for which to search for an element in the ArrayList. For more information on those methods, refer to the .NET Framework SDK documentation.

Working with the Hashtable Class

The type of collection most developers are used to working with is the hash table collection. Whereas the ArrayList indexes each element numerically, a hash table indexes each element by an alphanumeric key. The Collection data type in Visual Basic is a hash table; the Scripting.Dictionary object, used commonly in classic ASP pages, is a simple hash table. The .NET Framework provides developers with a powerful hash table class, Hashtable.

When working with the Hashtable class, keep in mind that the ordering of elements in the collection are irrespective of the order in which they are entered. The Hashtable class employs its own hashing algorithm to efficiently order the key/value pairs in the collection. If it is essential that a collection's elements be ordered alphabetically by the value of their keys, use the SortedList class, which is discussed in the next section, "Working with the SortedList Class."

Adding, Removing, and Indexing Elements in a Hashtable

With the ArrayList class, there were a number of ways to add various elements to various positions in the ArrayList. With the Hashtable class, there aren't nearly as many options because there is no sequential ordering of elements. To add new elements to a Hashtable use the Add method.

Not surprisingly, there are also fewer methods to remove elements from a Hashtable. The Remove method dissects a single element, whereas the Clear method removes all elements from a Hashtable. Examples of both of these methods can be seen in Listing 2.1.2. The output is shown in Figure 2.2.

Listing 2.1.2 For Sequentially Accessed Collections, Use the ArrayList

 1: <script language="VB" runat="server">
 2:
 3:  Sub Page_Load(sender as Object, e as EventArgs)
 4:   ' Create a HashTable
 5:   Dim htSalaries As New Hashtable()
 6:
 7:   ' Use the Add method to add Employee Salary Information
 8:   htSalaries.Add("Bob", 40000)
 9:   htSalaries.Add("John", 65000)
10:   htSalaries.Add("Dilbert", 25000)
11:   htSalaries.Add("Scott", 85000)
12:   htSalaries.Add("BillG", 90000000)
13:
14:   ' Now, display a list of employees and their salaries
15:   lblSalary.Text = "<i>There are " & htSalaries.Count & _
16:           " Employees...</i><br>"
17:
18:   Dim s as String
19:   For Each s in htSalaries.Keys
20:    lblSalary.Text &= s & " - " & htSalaries(s) & "<br>"
21:   Next
22:
23:   ' Is BillG an Employee? If so, FIRE HIM!
24:   If htSalaries.ContainsKey("BillG") Then
25:    htSalaries.Remove("BillG")
26:   End If
27:
28:
29:   ' List the remaining employees (using databinding)
30:   dgEmployees.DataSource = htSalaries.Keys
31:   dgEmployees.DataBind()
32:
33:
34:   htSalaries.Clear() ' remove all entries in hash table...
35:  End Sub
36:
37: </script>
38:
39: <html>
40: <body>
41:  <b>Employee Salary Information:</b><br>
42:  <asp:label id="lblSalary" runat="server" />
43:  <p>
44:
45:  <b>Remaining Employees After Round One of Firings:</b><br>
46:  <asp:datagrid runat="server" id="dgEmployees"
47:         AutoGenerateColumns="True" ShowHeader="False"
48:         CellSpacing="1" CellPadding="4" />
49: </body>
50: </html>

Figure 2.2
Output of Listing 2.1.2 when viewed through a browser.

Adding Elements to a Hashtable

In Listing 2.1.2, we begin by creating an instance of the Hashtable class, htSalaries, on line 5. Next, we populate this hash table with our various employees and their respective salaries on lines 7 through 12. Note that the Add method, which adds an element to the Hashtable collection, takes two parameters: the first is an alphanumeric key by which the element will be referenced, and the second is the element itself, which needs to be of type Object.

In Listing 2.1.2, we are storing integer values in our Hashtable class. Of course we are not limited to storing just simple data types; rather, we can store any type of Object. As we'll see in an example later in this chapter, we can even create collections of collections (collections whose elements are also collections)!

Removing Elements from a Hashtable

The Hashtable class contains two methods to remove elements: Remove and Clear. Remove expects a single parameter, the alphanumeric key of the element to be removed. Line 25 demonstrates this behavior, removing the element referred to as "BillG" in the hash table. On line 34 we remove all the elements of the hash table via the Clear method. (Recall that all collection types contain a Clear method that demonstrates identical functionality.)

The Hashtable class contains two handy methods for determining whether a key or value exists. The first function, ContainsKey, takes a single parameter, the alphanumeric key to search for. If the key is found within the hash table, ContainsKey returns True. If the key is not found, ContainsKey returns False. In Listing 2.1.2, this method is used on line 24. The Hashtable class also supports a method called ContainsValue. This method accepts a single parameter of type Object and searches the hash table to see if any element contains that particular value. If it finds such an element, ContainsValue will return True; otherwise, it will return False. The ContainsKey and ContainsValue methods are used primarily for quickly determining whether a particular key or element exists in a Hashtable.

On line 24, a check was made to see if the key "BillG" existed before the Remove method was used. Checking to make sure an item exists before removing it is not required. If you use the Remove method to try to remove an element that does not exist (for example, if we had Remove("Homer") in Listing 2.2.1), no error or exception will occur.

The Keys and Values Collections

The Hashtable class exposes two collections as properties: Keys and Values. The Keys collection is, as its name suggests, a collection of all the alphanumeric key values in a Hashtable. Likewise, the Values collection is a collection of all the element values in a Hashtable. These two properties can be useful if you are only interested in, say, listing the various keys.

On line 30 in Listing 2.1.2, the DataSource property of the dgEmployees DataGrid is set to the Keys collection of the hySalaries Hashtable instance. Because the Keys property of the Hashtable class returns an ICollection interface, it can be bound to a DataGrid using data binding. For more information on data binding and using the DataGrid, refer to Chapter 7, "Data Presentation."

Working with the SortedList Class

So far we've examined two collections provided by the .NET Framework: the Hashtable class and the ArrayList class. Each of these collections indexes elements in a different manner. The ArrayList indexes each element numerically, whereas the Hashtable indexes each element with an alphanumeric key. The ArrayList orders each element sequentially, based on its numerical index; the Hashtable applies a seemingly random ordering (because the order is determined by a hashing algorithm).

What if you need a collection, though, that allows access to elements by both an alphanumeric key and a numerical index? The .NET Framework includes a class that permits both types of access, the SortedList class. This class internally maintains two arrays: a sorted array of the keys and an array of the values.

Adding, Removing, and Indexing Elements in a SortedList

Because the SortedList orders its elements based on the key, there are no methods that insert elements in a particular spot. Rather, similar to the Hashtable class, there is only a single method to add elements to the collection: Add. However, because the SortedList can be indexed by both key and value, the class contains both Remove and RemoveAt methods. As with all the other collection types, the SortedList also contains a Clear method that removes all elements.

Because a SortedList encapsulates the functionality of both the Hashtable and ArrayList classes, it's no wonder that the class provides a number of methods to access its elements. As with a Hashtable, SortedList elements can be accessed via their keys. A SortedList that stored Integer values could have an element accessed similar to the following:

Dim SortedListValue as Integer
SortedListValue = slSortedListInstance(key)

The SortedList also can access elements through an integral index, like with the ArrayList class. To get the value at a particular index, you can use the GetByIndex method as follows:

Dim SortedListValue as Integer
SortedListValue = slSortedListInstance.GetByIndex(iPosition)

iPosition represents the zero-based ordinal index for the element to retrieve from slSortedListInstance. Additionally, elements can be accessed by index using the GetValueList method to return a collection of values, which can then be accessed by index:

Dim SortedListValue as Integer
SortedListVluae = slSortedListInstance.GetValueList(iPosition)

Listing 2.1.3 illustrates a number of ways to retrieve both the keys and values for elements of a SortedList. The output is shown in Figure 2.3.

Listing 2.1.3 A SortedList Combines the Functionality of a Hashtable and ArrayList

 1: <script language="VB" runat="server">
 2:  Sub Page_Load(sender as Object, e as EventArgs)
 3:   ' Create a SortedList
 4:   Dim slTestScores As New SortedList()
 5:
 6:   ' Use the Add method to add students' Test Scores
 7:   slTestScores.Add("Judy", 87.8)
 8:   slTestScores.Add("John", 79.3)
 9:   slTestScores.Add("Sally", 94.0)
10:   slTestScores.Add("Scott", 91.5)
11:   slTestScores.Add("Edward", 76.3)
12:
13:   ' Display a list of test scores
14:   lblScores.Text = "<i>There are " & slTestScores.Count & _
15:           " Students...</i><br>"
16:   Dim dictEntry as DictionaryEntry
17:   For Each dictEntry in slTestScores
18:    lblScores.Text &= dictEntry.Key & " - " & dictEntry.Value & "<br>"
19:   Next
20:
21:   'Has Edward taken the test? If so, reduce his grade by 10 points
22:   If slTestScores.ContainsKey("Edward") then
23:    slTestScores("Edward") = slTestScores("Edward") - 10
24:   End If
25:
26:   'Assume Sally Cheated and remove her score from the list
27:   slTestScores.Remove("Sally")
28:
29:   'Grade on the curve - up everyone's score by 5 percent
30:   Dim iLoop as Integer
31:   For iLoop = 0 to slTestScores.Count - 1
32:    slTestScores.GetValueList(iLoop) = _
33:           slTestScores.GetValueList(iLoop) * 1.05
34:   Next
35:
36:   'Display the new grades
37:   For iLoop = 0 to slTestScores.Count - 1
38:    lblCurvedScores.Text &= slTestScores.GetKeyList(iLoop) & " - " & _
39:          String.Format("{0:#.#}", slTestScores.GetByIndex(iLoop))
 & "<br>"
40:   Next
41:
42:   slTestScores.Clear() ' remove all entries in the sorted list...
43:  End Sub
44: </script>
45:
46: <html>
47: <body>
48:  <b>Raw Test Results:</b><br>
49:  <asp:label id="lblScores" runat="server" />
50:  <p>
51:
52:  <b>Curved Test Results:</b><br>
53:  <asp:label id="lblCurvedScores" runat="server" />
54: </body>
55: </html>

Figure 2.3
Output of Listing 2.1.3 when viewed through a browser.

Listing 2.1.3 begins with the instantiation of the SortedList class (line 4). slTestScores, the SortedList instance, contains the test scores from five students (see lines 7 through 11). Each element of a SortedList really is represented by the DictionaryEntry structure. This simple structure contains two public fields: Key and Value. Starting at line 17, we use a For Each ... Next loop to step through each DictionaryEntry element in our SortedList slTestScores. On line 18, we output the Key and Value, displaying the student's name and test score. Be sure to examine Figure 2.3 and notice that the displayed results are ordered by the value of the key.

On line 22, the ContainsKey method is used to see if Edward's score has been recorded; if so, it's reduced by ten points. (Poor Edward.) Note that we access the value of Edward's test score using the element's key—slTestScores("Edward")—just as if slTestScores were a Hashtable (line 23). On line 27, Sally's test score is removed from the SortedList via the Remove method.

Next, each remaining student's test score is upped by 5 percent. On lines 31 through 34, each test score is visited via a For ... Next loop (which is possible because SortedList elements can be accessed by an index). Because .NET collections are zero-based, notice that we loop from 0 to slTestScores.Count - 1 (line 31). On line 32, the value of each element is accessed via the GetValueList method, which returns a collection of values; this collection can then be indexed numerically.

On lines 37 through 40, another For ... Next loop is used to display the curved test results. On line 38, the GetKeyList method is used to return a collection of keys (which is then accessed by index); on line 39, the test results are outputted using the String.Format function. The format string passed to the String.Format function ("{0:#.#}") specifies that the first parameter following the format string (slTestScores.GetByIndex(iLoop), the test results) should only display one decimal place. Finally, on line 42, all the test results are erased with a single call to the Clear method.

Working with the Queue Class

ArrayLists, Hashtables, and SortedLists all have one thing in common—they allow random access to their elements. That is, a developer can programmatically read, write, or remove any element in the collection, regardless of its position. However, the Queue and Stack classes (the remaining two collections we'll examine) are unique in that they provide sequential access only. Specifically, the Queue class can only access and remove elements in the order they were inserted.

Adding, Removing, and Accessing Elements in a Queue

Queues are often referred to as First In, First Out (FIFO) data structures because the Nth element inserted will be the Nth element removed or accessed. It helps to think of the queue data structure as a line of people. There are two parts to a queue as there are two parts to any line up: the tail of the queue, where people new to the line start waiting, and the head of the queue, where the next person in line waits to be served. In a line, the person who is standing in line first will be first served; the person standing second will be served second, and so on. In a queue, the element that is added first will be the element that is removed or accessed first, whereas the second element added will be the second element removed or accessed.

The .NET Framework provides support for the queue data structure with the Queue class. To add an element to the tail, use the Enqueue method. To retrieve and remove an element from the head of a queue, use Dequeue. As with the other collection types we've examined thus far, the Queue class contains a Clear method to remove all elements. To simply examine the element at the head without altering the queue, use the Peek method. As with all the other collections, the elements of a Queue can be iterated through using an enumerator or a For Each ... Next loop. Listing 2.1.4 illustrates some simple queue operations. The output is shown in Figure 2.4.

Listing 2.1.4 A Queue Supports First In, First Out Element Access and Removal

 1: <script language="VB" runat="server">
 2:
 3:  Sub Page_Load(sender as Object, e as EventArgs)
 4:   ' Create a Queue
 5:   Dim qTasks as New Queue()
 6:
 7:   qTasks.Enqueue("Wake Up")
 8:   qTasks.Enqueue("Shower")
 9:   qTasks.Enqueue("Get Dressed")
10:   qTasks.Enqueue("Go to Work")
11:   qTasks.Enqueue("Work")
12:   qTasks.Enqueue("Come Home")
13:   qTasks.Enqueue("Eat Dinner")
14:   qTasks.Enqueue("Go to Sleep")
15:
16:   ' To determine if an element exists in the Queue,
17:   ' use the Contains method
18:   If Not qTasks.Contains("Shower") Then
19:    ' Forgot to bathe!
20:    Response.Write("<b><i>Stinky!</i></b>")
21:   End If
22:
23:   ' Output the list of tasks
24:   lblTaskList.Text &= "<i>There are " & qTasks.Count & _
25:            " tasks for today...</i><br>"
26:
27:   Dim iCount as Integer = 1
28:   Do While qTasks.Count > 0
29:    lblTaskList.Text &= iCount.ToString() & ".) " & _
30:              qTasks.Dequeue() & "<br>"
31:    iCount += 1
32:   Loop
33:
34:
35:   ' At this point the queue is empty, since we've
36:   ' Dequeued all of the elements.
37:  End Sub
38:
39: </script>
40:
41: <html>
42: <body>
43:
44:  <b>An In-Order List of Tasks for the Day:</b><br>
45:  <asp:label runat="server" id="lblTaskList" />
46:
47: </body>
48: </html>

Figure 2.4
Output of Listing 2.1.4 when viewed through a browser.

Adding Elements to a Queue

In Listing 2.1.4, we begin by creating an instance of the Queue class, qTasks (line 5). In line 7 through 14, we add eight new elements to qTasks using the Enqueue method. Recall that a queue supports First In, First Out ordering, so when we get ready to remove these elements, the first element to be removed will be "Wake Up", which was the first element added.

To quickly check if a particular element is an element of the queue, you can use the Contains method. Line 18 demonstrates usage of the Contains method. Note that it takes a single parameter, the element to search for, and returns True if the element is found in the queue and False otherwise.

Removing Elements from a Queue

With a Queue, you can only remove the element at the head. With such a constraint, it's no wonder that the Queue class only has a single member to remove an element: Dequeue. Dequeue not only removes the element at the head of the queue, but it also returns the element just removed.

If you attempt to remove an element from an empty Queue, the InvalidOperationException exception will be thrown and you will receive an error. Therefore, to prevent producing a runtime error in your ASP.NET page, be sure to either place the Dequeue statement in a Try ... Catch ... Finally block or ensure that the Count property is greater than zero (0) before using Dequeue. (For more information on Try ... Catch ... Finally blocks, refer to Chapter 9, "ASP.NET Error Handling." For an example of checking the Count property prior to using Dequeue, see lines 28 through 32 in Listing 2.1.4.) As with all the other collection types, you can remove all the Queue elements with a single call to the Clear method (line 36).

There might be times when you want to access the element at the head of the Queue without removing it from the Queue. This is possible via the Peek method, which returns the element at the head of the Queue without removing it. As with the Dequeue method, if you try to Peek an empty Queue, an InvalidOperationException exception will be thrown.

Iterating Through the Elements of a Queue

One way to iterate through the elements of a Queue is to simply use Dequeue to successively grab each item off the head. This approach can be seen in lines 27 through 32 in Listing 2.1.4. The major disadvantage of this approach is that, after iteration is complete, the Queue is empty!

As with every other collection type, the Queue can be iterated via a For Each ... Next loop or through the use of an enumerator. The following code snippet illustrates using the C# foreach statement to iterate through all the elements of a Queue without affecting the structure:

Queue qMyQueue = new Queue();  // Create a Queue

qMyQueue.Enqueue(5);
qMyQueue.Enqueue(62);  // Add some elements to the Queue
qMyQueue.Enqueue(-7);

// Iterate through each element of the Queue, displaying it
foreach (int i in qMyQueue)
 Response.Write("Visiting Queue Element with Value: " + i + "<br>");

Working with the Stack Class

A stack is a data structure similar to a queue in that it supports only sequential access. However, a stack does bear one major difference from a queue: Rather than storing elements with a First In, First Out (FIFO) semantic, a stack uses Last In, First Out (LIFO). A crowded elevator behaves similar to a stack: The first person who enters the crowded elevator is the last person to leave, whereas the last person to board the elevator is the first out when it reaches its destination.

Adding, Removing, and Accessing Elements in a Stack

The .NET Framework provides an implementation of the stack data type with the Stack class. A stack has two basic operations: adding an element to the top of the stack, which is accomplished with the Push method, and removing an element from the top of the stack, accomplished via the Pop method. Similar to the Queue class, the Stack class also contains a Peek method to permit developers to access the top of the stack without removing the element.

Up until this point, the code provided in the previous listings has just given you a feel for the syntax of the various collections. Listing 2.1.5, however, contains a handy little piece of reusable code that can be placed on each page of your Web site to provide a set of navigation history links for your visitors.

The code in Listing 2.1.5 uses a session-level Stack class instance that is used to store the links that a Web visitor has traversed on your site since the start of his session. Each time a user visits a Web page, the stack is displayed in a history label and the page's URL is pushed onto the stack. As the user visits various pages on your Web site, his navigation history stack will continue to grow and he will be able to quickly jump back to previous pages on your site. Basically, this is mimicking the functionality of a browser's Back button. The output is shown in Figure 2.5.

Listing 2.1.5 A Stack Is Ideal for Keeping Track of a User's Navigation History

 1: <script language="c#" runat="server">
 2:
 3:  void Page_Load(Object sender, EventArgs e)
 4:  {
 5:   // See if we have a stack created or not:
 6:   if (Session["History"] == null)
 7:   {
 8:    // the history stack has not been created, so create it now.
 9:    Session["History"] = new Stack();
10:   } else {
11:    // we already have a history stack. Display the history:
12:    IEnumerator enumHistory =
13:        ((Stack) Session["History"]).GetEnumerator();
14:    while (enumHistory.MoveNext())
15:     lblStackHistory.Text += "<a href=\"" + enumHistory.Current +
16:                 "\">" + enumHistory.Current +
17:                 "</a><br>";
18:   }
19:
20:   // Push current URL onto Stack IF it is not already on the top
21:   if (((Stack) Session["History"]).Count > 0)
22:   {
23:    if(((Stack) Session["History"]).Peek().ToString() !=
24:                   Request.Url.PathAndQuery.ToString())
25:     ((Stack) Session["History"]).Push(Request.Url.PathAndQuery);
26:   } else
27:    ((Stack) Session["History"]).Push(Request.Url.PathAndQuery);
28:  }
29:
30: </script>
31:
32: <html>
33: <body>
34:   <b>Session History</b><br>
35:   <asp:label runat=server id="lblStackHistory" /><br>
36:
37:   <a href="ClearStackHistory.CSharp.aspx">Clear Stack History</a><br>
38:   <a href="Back.CSharp.aspx">Back</a>
39:
40:   <p>
41:   <b>Links:</b><br>
42:   <li><a href="Listing2.1.5.aspx">Listing2.1.5.aspx</a><br>
43:   <li><a href="Listing2.1.5.b.aspx">Listing2.1.5.b.aspx</a><br>
44: </body>
45: </html>

Figure 2.5
Output of Listing 2.1.5 when viewed through a browser.

If you've worked with classic ASP, you are likely familiar with the concept of session-level variables. These variables are defined on a per-user basis and last for the duration of the user's visit to the site. These variables are synonymous with global variables in that their values can be accessed across multiple ASP pages. Session-level variables, which are discussed in greater detail in Chapter 14, "Managing State," are a simple way to maintain state on a per-user basis. Because we want the user's navigation history stack to persist as the user bounces around our site, we will store the Stack class instance in a session-level variable.

To implement a navigation history stack as a session-level variable, we must make sure that we have created such a variable before trying to reference it. Keep in mind that when a visitor first comes to our site and visits that first page, the session-level variable will not be instantiated. Therefore, on each page, before we refer to the navigation history stack, it is essential that we check to ensure that our session-variable, Session["History"], has been assigned to an instance of the Stack class.


Note

To access a session variable using C#, the braces are used around the session variable name. For example, to retrieve the value of the History session variable with C# we'd use:

Session["History"],

With VB.NET, however, parentheses are used in place of the brackets:

Session("History")

Line 6 in Listing 2.1.5 checks Session["History"] to determine whether it references a Stack object instance. If Session["History"] has not been assigned an object instance, it will equal null (or Nothing, in VB). If Session["History"] is null, we need to set it to a newly created instance of the Stack class (line 9).

However, if Session["History"] is not null, we know that the user has already visited at least one other page on our site. Therefore, we can display the contents of the Session["History"] Stack. This is accomplished in lines 12 through 17 with the use of an enumerator. We'll discuss iteration through collections via enumerators in the next section, "Similarities Among the Collection Types." With C#, as opposed to VB, explicit casting must be done when working with the Session object. For example, on line 13, before we can call the GetEnumerator() method (a method of the Stack class), we must cast the Session["History"] variable to a Stack:

// C# code must use an explicit cast
IEnumerator enumHistory = ((Stack) Session["History"]).GetEnumerator();

'VB code, however, does not require an explicit cast
Dim enumHistory As IEnumerator = Session("History").GetEnumerator()

With VB, however, such a cast is not necessary. Casting issues with the Session object are discussed in more detail in Chapter 14.

After either creating a new session-level Stack instance or displaying the Stack's contents, we're ready to add the current URL to the navigation history stack. This could be accomplished with the following simple line of code:

((Stack) Session["History"]).Push(Request.Url.PathAndQuery);

However, if the user refreshed the current page, it would, again, get added to the navigation history stack. It would be nice not to have the same page repeatedly appear in the navigation history stack. Therefore, on line 23, we use the Peek method to see if the top-most element in the Stack is not equal to the current URL. If the top-most element of the stack is not equal to the current URL, we Push the current URL onto the top of the stack, otherwise we do nothing.

Before we use the Peek method, we first determine whether the Stack is empty. Recall from the previous section, "Working with the Queue Class," using the Peek method on an empty Queue will raise an InvalidOperationException exception. This is the same case with the Stack class; therefore, on line 21, we first check to ensure that at least one element is in the Stack before using the Peek method.

Two useful utility ASP.NET pages have been created to provide some extra functionality for our navigation history stack. The fist page, ClearStackHistory.Csharp.aspx, erases the contents of the history stack and is presented in Listing 2.1.6. The second page, Back.Csharp.aspx, serves like a back button in the user's browser, taking him to the previously visited page. The code for Back.Csharp.aspx is given in Listing 2.1.7. We'll examine these two code listings momentarily.

Listing 2.1.5 also contains a link to another ASP.NET page, Listing2.1.5.b.aspx. This page is identical to Listing2.1.5.aspx. In your Web site, you would need to, at a minimum, include the code in Listing 2.1.5 in each ASP.NET page to correctly keep the navigation history up-to-date.

Listing 2.1.6 ClearStackHistory.CSharp.aspx Erases the Contents of the Navigation History Stack

 1: <script language="c#" runat="server">
 2:
 3:  void Page_Load(Object sender, EventArgs e)
 4:  {
 5:   // See if we have a stack created or not:
 6:   if (Session["History"] == null)
 7:   {
 8:    // There's no Stack, so we don't need to do anything!
 9:   } else {
10:    // we need to clear the stack
11:    ((Stack) Session["History"]).Clear();
12:   }
13:  }
14:
15: </script>
16:
17: <html>
18: <body>
19:   Your navigation history has been cleared!
20: </body>
21: </html>

Listing 2.1.6 contains the code for ClearStackHistory.CSharp.aspx. This code only has a single task—clear the contents of the navigation history stack—and therefore is fairly straightforward. The ASP.NET page starts by checking to determine if Session["History"] refers to a Stack object instance (line 6). If it does, the Clear method is used to erase all the stack's elements (line 11).

The code for the second utility page, Back.CSharp.aspx, can be seen in Listing 2.1.7.

Listing 2.1.7 Back.CSharp.aspx Sends the User to the Previous Page in His Navigation History Stack

 1: <script language="c#" runat="server">
 2:  void Page_Load(Object sender, EventArgs e)
 3:  {
 4:   // See if we have a stack created or not:
 5:   if (Session["History"] == null ||
 6:     ((Stack) Session["History"]).Count < 2)
 7:   {
 8:    // There's no Stack, so we can't go back!
 9:    Response.Write("Egad, I can't go back!");
10:   } else {
11:    // we need to go back to the prev. page
12:    ((Stack) Session["History"]).Pop();
13:    Response.Redirect(((Stack) Session["History"]).Pop().ToString());
14:   }
15:  }
16: </script>

As with ClearStackHistory.CSharp.aspx, Back.CSharp.aspx starts by checking to determine if Session["History"] is null. If that is the case, a warning message is displayed because we can't possibly step back through our navigation history stack if it doesn't exist!

Take a moment to briefly look over Listing 2.1.5 again. Note that on each page we visit, we add the current URL to the stack. Therefore, if we want to go back to the previous page, we can't just pluck off the top element from the stack (because that contains the current URL). Rather, we must pluck off the top-most item, dispose of it, and then visit the next item on the top of the stack. For that reason, our stack must have at least two elements to be able to traverse back to the previous page. On line 6, we check to make sure that the navigation history stack contains at least two elements.

Given that we have a properly defined navigation history stack—that is, Session["History"] is not null and there are at least two elements in the Stack—we will reach lines 12 and 13, which do the actual work of sending the user back to the previous page. Line 12 simply disposes of the top-most Stack element; line 13 uses the Redirect method of the Response object to send the user to the next element at the top of the stack.

That wraps up our examination of the navigation history stack example. The code samples spanned three listings: Listing 2.1.5, Listing 2.1.6, and Listing 2.1.7. If you decide to use this code on your Web site, there are a couple of things to keep in mind:

  • First, because our implementation of the navigation history stack is a code snippet in an ASP.NET page, the code in Listing 2.1.5 would need to appear in every Web page on your site. This, of course, is a ridiculous requirement; it would make sense to encapsulate the code and functionality in a user control to allow for easy code reuse. (For more information on user controls, refer to Chapter 5, "Creating and Using User Controls.")

  • Second, remember that in Back.CSharp.aspx we are Popping off the top two URLs. Because Pop removes these elements from the Stack altogether, the navigation history stack cannot contain any sort of Forward link.

Similarities Among the Collection Types

Because each collection has the same basic functionality—to serve as a variable-sized storage medium for Objects—it is not surprising that the collection types have much in common with one another. All have methods to add and remove elements from the collection. The Count property, which returns the total number of elements in the collection, is common among all collection types.

Each collection also has a means to iterate through each element. This can be accomplished in VB using a For Each ... Next loop or, in C#, a foreach loop, as follows:

'With VB, use a For Each ... Next Loop
Dim qTasks as Queue = New Queue()

' ... Populate the Queue ...

Dim s as String
For Each s in qTasks
 's represents the current element in qTasks
 Response.Write(s + "<br>")
Next


// In C#, a foreach construct can be used to iterate
// through each element
Queue qTasks = new Queue();

// ... Populate the Queue ...

foreach (String s in qTasks)
{
  // s represents the current element in qTasks
  Response.Write(s + "<br>");
}

Although each collection can be iterated via a For Each ... Next or foreach loop, each collection can also have its elements iterated with an enumerator. Enumerators are small classes that provide a simple functionality: to serve as a (read-only) cursor to allow the developer to step through the elements of a collection.

The .NET Framework provides a number of specific enumerators for specific collection types. For example,the IDictionaryElement enumerator is useful for iterating through a Hashtable. The IList enumerator is handy for stepping through the elements of an ArrayList. All these specialized enumerators are derived from a base enumerator interface, IEnumerator. Because of this fact, all the collection types can be iterated via the IEnumerator enumerator as well.

Because an enumerator's most basic purpose is to serve as a cursor for a collection, the IEnumerator class contains only a single property that returns the element in the collection to which the enumerator is currently pointing. (More specialized enumerators, such as IDictionaryElement, contain multiple properties.) IEnumerator contains just two methods: MoveNext, which advances the enumerator to the next element in the collection, and Reset, which returns the enumerator to its starting position—the position immediately before the first element in the collection.

Listing 2.1.8 contains a simple ASP.NET page that illustrates iteration through both an ArrayList and Hashtable with the IEnumerator enumerator. The output is shown in Figure 2.6.

Listing 2.1.8 To Step Through Each Element of a Collection, an Enumerator Can Be Used

 1: <script language="VB" runat="server">
 2:
 3:  Sub Page_Load(sender as Object, e as EventArgs)
 4:   ' Create some Collections
 5:   Dim aTeam1 as New ArrayList(), _
 6:     aTeam2 as New ArrayList(), _
 7:     aTeam3 as New ArrayList()
 8:
 9:   Dim htProjects as New Hashtable()
10:
11:   ' Assign memebers to the various teams
12:   aTeam1.Add("Scott")
13:   aTeam1.Add("Rob")
14:   aTeam1.Add("Chris")
15:
16:   aTeam2.Add("Doug")
17:   aTeam2.Add("Don")
18:
19:   aTeam3.Add("Billy")
20:   aTeam3.Add("Mark")
21:   aTeam3.Add("Charles")
22:   aTeam3.Add("Steve")
23:
24:
25:   ' Add each team to the htProjects HashTable
26:   htProjects.Add("Prototyping", aTeam1)
27:   htProjects.Add("Coding", aTeam2)
28:   htProjects.Add("Testing", aTeam3)
29:
30:   ' Now, list each project
31:   Dim enumProjects as IEnumerator = htProjects.GetEnumerator()
32:   Do While enumProjects.MoveNext()
33:    lblProjectListing.Text &= enumProjects.Current.Key & "<br>"
34:   Loop
35:
36:   ' Now list each team
37:   Dim enumTeam as IEnumerator
38:   enumProjects.Reset()
39:   Do While enumProjects.MoveNext()
40:     lblDetailedListing.Text &= "<b>" & enumProjects.Current.Key 
 & ":</b><ul>"
41:
42:     enumTeam = enumProjects.Current.Value.GetEnumerator()
43:     Do While enumTeam.MoveNext()
44:      lblDetailedListing.Text &= enumTeam.Current & "<br>"
45:     Loop
46:
47:     lblDetailedListing.Text &= "</ul><p>"
48:   Loop
49:  End Sub
50:
51: </script>
52:
53: <html>
54: <body>
55:
56:  <font size=+1><b><u>Project Listing:</u></b></font><br>
57:  <asp:label runat="server" id="lblProjectListing" />
58:  <p>
59:
60:  <font size=+1><b><u>Detailed Project Listing</u>:</b></font><br>
61:  <asp:label runat="server" id="lblDetailedListing" />
62:
63: </body>
64: </html>

Figure 2.6
Output of Listing 2.1.8 when viewed through a browser.

The code in Listing 2.1.8 begins by creating three ArrayList collections: aTeam1, aTeam2, and aTeam3 (lines 5, 6, and 7, respectively). These three ArrayLists are then populated with various strings in lines 12 through 22. Each of these ArrayLists is added to the htProjects HashTable on lines 26 through 28. As pointed out earlier, collection types can hold any Object, not just simple data types such as integers and strings.

On line 31, an instance of the IEnumerator interface is created and assigned to the enumerator for htProjects. (Each of the collection types contains a GetEnumerator() method that returns a read-only enumerator for the collection.) From lines 32 to 34, the enumProjects enumerator is stepped through, visiting each element in the Hashtable collection.

Note that each element returned to the enumerator from a Hashtable is an instance of the DictionaryEntry object. The DictionaryEntry object contains two public fields: Key and Value. Therefore, on line 33, to obtain the key of the current Hashtable element, we need to specify that we want the Key field of the current element. We could have created a DictionaryEntry instance and referenced the Key field in a more explicit manner as follows:

Dim dictEntry as DictionaryEntry
Do While enumProjects.MoveNext()
 dictEntry = enumProjects.Current
 lblProjectListing.Text &= dictEntry.Key & "<br>"
Loop

Because each entry in htProjects is an ArrayList collection itself, we need to create another enumerator to step through each element in each ArrayList. This is accomplished on line 37. At the end of our iteration through htProjects in lines 32 through 34, the enumerator enumProjects is positioned at the end of the collection. Because we are going to iterate through the htProjects collection again, we need to reposition the enumerator back to before the first element. This is accomplished with the Reset method of the IEnumerator interface (line 38).

In lines 39 through 48, the htProjects collection is enumerated through again. This time, each element of htProjects is also iterated through itself. On line 42, the enumTeam enumerator is assigned via the GetEnumerator() method of the current ArrayList collection. Next, the enumTeam enumerator is stepped through in lines 43 through 45, outputting each ArrayList element (line 44).

Conclusion

The .NET Framework provides developers with a number of powerful collection-type classes, greatly extending the functionality of the Scripting.Dictionary object, the sole collection type available for classic ASP developers. These collections, although each have unique capabilities, are more alike than they are different. All of them share similar methods and properties, and can have their elements iterated through using a number of techniques.


Note

All of the collection types we've examined in this chapter inherit from the ICollection interface. This interface is responsible for providing the size, enumeration, and synchronization methods for collection types. All of the classes in the .NET Framework that inherit the ICollection interface support the basic collection functionality discussed in this section, "Similarities Among the Collection Types."


  • Read Part 2


  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article