www.gibmonks.com

Main Page

  Previous Section Next Section

16.3 Collections Reference

The Request object in ASP.NET supports seven collections, four of which were supported in ASP (Cookies, Forms, QueryString, and ServerVariables), and three of which are new (Files, Headers, and Params).

The collections of the Request class support the following common set of properties:

AllKeys

Returns a string array of all keys in the collection.

Count

Returns an integer count of name/value pairs in the collection.

Item(Index|Key)

Returns an instance of the collection class based on the index or passed-in key. This is the default property, which is why, for example, calling:

Response.Cookies (KeyVal)

returns the HttpCookie instance corresponding to KeyVal.

Keys

Returns a collection of the keys for the collection.

In addition, each collection class exposes the following methods:

CopyTo(Array, Index)

Copies the contents of the collection object to the provided Array argument, starting at the provided Index argument. Note that the array must be dimensioned to a sufficient size to contain the collection before calling CopyTo.

GetKey(Index)

Returns a string containing the key corresponding to the provided Index argument.

With the exception of the Cookies collection, the code used to access keys and values in the collections the Request class exposes is nearly identical in every case. This similarity makes it simple to create your own reusable classes or methods for manipulating the values from these collections, regardless of which collection you are working with.

Cookies

HttpCookieCollection = Request.Cookies

The Cookies collection returns an instance of the HttpCookieCollection class containing all cookies sent as a part of the current request. The HttpCookieCollection class contains an instance of the HttpCookie class for each cookie passed as part of the client request. The properties of these HttpCookie instances can be used to access information about the cookie(s).

As in classic ASP, the Cookies collection is still implemented as a collection (in fact, the HttpCookieCollection inherits from the .NET NameObjectCollectionBase class), but rather than a collection of string keys and string values, the ASP.NET implementation is a collection of string keys and objects (instances of the HttpCookie class). Individual cookies are retrieved into variables of type HttpCookie, providing access to the cookies' values through class properties.

Dictionary-style cookies (cookies with more than one value) are accessible through the Values property of the HttpCookie class, which returns a NameValueCollection containing the cookie subkeys and values. You can also retrieve individual values by their key with the following syntax:

HttpCookie.Values("keyname")

Parameter

HttpCookieCollection

An Object variable of type HttpCookieCollection.

Example

The example retrieves the collection of cookies from the Cookies property and writes out the key and value of each, along with any subkeys of dictionary cookies:

Sub Page_Load( )
   Dim Counter1, Counter2 As Integer
   Dim Keys( ), SubKeys( ) As String
   Dim CookieColl As HttpCookieCollection 
   Dim Cookie As HttpCookie
  
   ' Get Cookie collection
   CookieColl = Request.Cookies
  
   ' Get Cookie keys
   Keys = CookieColl.AllKeys
  
   ' Get cookies by index
   For Counter1 = 0 To Keys.GetUpperBound(0)
      Cookie = CookieColl(Keys(Counter1))
      Message.Text = "Cookie: " & Cookie.Name & "<br/>"
      Message.Text &= "Expires: " & Cookie.Expires & "<br/>"
  
      ' Get keys for dictionary cookie into an array
      SubKeys = Cookie.Values.AllKeys
      ' Write dictionary cookie values to the browser
      For Counter2 = 0 To SubKeys.GetUpperBound(0)
         Message.Text &= "Key " & CStr(Counter2) + ": " & _
            SubKeys(Counter2) & "<br/>"
         Message.Text &= "Value " & CStr(Counter2) + ": " & _
            Cookie.Values(Counter2) & "<br/>"
      Next Counter2
      Message.Text &= "<br/>"
   Next Counter1
End Sub

Notes

The ASP implementation of the Cookies collection and the HttpCookieCollection class returned by the Cookies property expose a common set of properties; these properties are described in Section 16.3.

While it is still possible in ASP.NET to retrieve an individual cookie by its text key as well as its numerical index, the differences in the operation make wholesale migration of ASP cookie-handling code to ASP.NET impractical without significant changes. For example, the following code will raise exceptions:

For Each strKey In Request.Cookies
   Response.Write strKey & " = " & Request.Cookies(strKey) & _
                  "<br/>"
   If Request.Cookies(strKey).HasKeys Then
      For Each strSubKey In Request.Cookies(strKey)
         Response.Write "->" & strKey & "(" & strSubKey & _
            ") = " & Request.Cookies(strKey)(strSubKey) & "<br/>"
      Next
   End If
Next

Apart from the fact that this code does not explicitly declare its variables or their types (both of which are required by default in ASP.NET), the previous code fails because the Request.Cookies(key) property returns an instance of HttpCookie, rather than a string, and the HttpCookie instance cannot be implicitly converted to a string for the Response.Write statement, which expects a string. Additionally, the call to Request.Cookies(key) does not get the subkeys for a dictionary cookie. Fortunately, the modifications necessary to make the previous code work are fairly simple and are shown here:

For Each strKey In Request.Cookies
   Message.Text = strKey & " = " & _
      Request.Cookies(strKey).ToString( ) & "<br/>"
   If Request.Cookies(strKey).HasKeys Then
      For Each strSubKey In Request.Cookies(strKey).Values
         Message.Text = "->" & strKey & "(" & strSubKey & _
            ") = " & Request.Cookies(strKey)(strSubKey).ToString( ) _
            & "<br/>"
      Next
   End If
Next

To solve the first issue, we use the HttpCookie's Value method to get the value of the cookie as a string. The solution to the second issue is to call the Values property of the HttpCookie instance, which allows us to retrieve the subkeys of a dictionary cookie.

Another quirk of the change from the mostly text-based manipulation of cookie keys and values in ASP to class-based manipulation in ASP.NET is that the Expires property of the HttpCookie class is available whether you read or write to a cookie. In ASP, however, attempting to read the Expires property of a cookie would result in an error. Unfortunately, at the time of this writing, the Expires property of HttpCookie does not actually return the expiration of the cookie. Instead, it returns the value 12:00:00 AM, which suggests that despite its readability, the property is not designed to be read from.

Finally, unlike classic ASP, the collections in ASP.NET are zero-based, so the first element in any collection or array is 0, not 1. This is especially important to remember when retrieving values by their index.

Files

HttpFileCollection = Request.Files

The Files collection, which is new to ASP.NET, returns a collection of type HttpFileCollection that contains any files uploaded by the user's current request. This collection is especially useful in combination with the HtmlInputFile Server Control, which provides the basic plumbing necessary to upload files via an HTTP POST request. When a user submits one or more files (one per HtmlInputFile control on the submitting page), you can retrieve the files by using the Files collection.

Parameter

HttpFileCollection

An Object variable of type HttpFileCollection.

Example

The example uses two HtmlInputFile server controls and a server-side <script> block to upload files and process them. The example shows both the <form> section of the page and its controls and the <script> block containing the UploadBtn_OnClick method called by the onServerClick event of the HtmlInputButton control:

<!--Place between the <head> and </head> tags -->
<script runat="server">
   Sub UploadBtn_Click(Sender as Object, e as EventArgs)
      UploadForm.Visible = False
      If InStr(Request.ContentType, "multipart/form-data") Then
         Dim Counter1 As Integer
         Dim Keys( ) As String
         Dim Files As HttpFileCollection
  
         ' Load File collection
         Files = Request.Files
         ' Get names of all files into an array
         Keys = Files.AllKeys
         For Counter1 = 0 To Keys.GetUpperBound(0)
            Message.Text &= "File ID: " & Keys(Counter1) & "<br/>"
            Message.Text &= "File Name/Path: " & _
               Files(Counter1).FileName & "<br/>"
         Next Counter1
      Else
         Message.Text = "Wrong content type!"
      End If
   End Sub
</script>
  
<!-- This section resides between the <body> and </body> tags -->
<form id="UploadForm" enctype="multipart/form-data" runat="server">
   Select File To Upload to Server: 
   <br/>
   <%-- MyFile and MyFile2 are HtmlInputFile controls --%>
   <%-- note the runat attribute --%>
   <input id="MyFile" type="file" runat="server">
   <br/>
   <input id="MyFile2" type="file" runat="server">
   <br/>
   <input id="Submit1" type="submit" value="Upload!"
      onserverclick="UploadBtn_Click" runat="server" >
</form>
<asp:label id="Message" runat="server"/>

Notes

In classic ASP, file uploading was a painful process that usually involved finding and purchasing a third-party upload control to use on the receiving ASP page to parse and save uploaded files. Thanks to the Files collection, you no longer need to locate and learn how to use third-party controls to upload files. This is bad for the control developers (although we suspect they'll more than make up for the loss by writing new Server Controls), but great for ASP.NET developers.

Two important points to remember about the Files collection to successfully upload files:

  • If using a client-side HTML form (no runat="server" attribute), set the method attribute of the form to POST.

  • Set the enctype attribute of the form to multipart/form-data.

The upload will succeed only if you take both steps. Note that the code example checks to see if the incoming request is multipart/form-data before attempting to retrieve the files.

It is not necessary to use the HtmlInputFile control to upload files that can be retrieved via the Files collection. As long as the submitting page uses the POST method and the multipart/form-data enctype attribute, you can use the standard HTML file input tags:

<input type="file" id="myFile" name="myFile">

Note the use of the name attribute, without which the files collection will not contain the uploaded file for the control.

Form

NameValueCollection = Request.Form

The Form collection returns an instance of the NameValueCollection class containing all form fields passed along with an HTTP POST request. This collection will contain data only when the Content-Type of the HTTP request is either application/x-www-form-urlencoded or multipart/form-data.

The Form collection is one of two ways to retrieve data, depending on the HTTP method used to submit the data. The Form collection retrieves data submitted by an HTML form whose method attribute is set to POST, while the QueryString collection (covered later in this section) retrieves values submitted by HTML forms whose method attribute is set to GET.

Parameter

NameValueCollection

An Object variable of type NameValueCollection.

Example

The example demonstrates how ASP.NET allows a single page to be used to submit values via HTTP POST and retrieve and display the values to the user. The example uses the IsPostBack property of the Page class to determine whether the request is a result of the form being submitted. If the request is not a postback, the form fields are displayed to allow the user to enter values. If the request is a postback, the page retrieves the Form collection and displays the name and value of each field in the browser.

Sub Page_Load( )
   If IsPostBack Then
      Form1.Visible = False
      If Request.HttpMethod = "POST" Then
         Dim Counter1 As Integer
         Dim Keys( ) As String
         Dim FormElements As NameValueCollection
  
         ' Get Form keys/elements
         FormElements=Request.Form
         ' Get names of form fields into array
         Keys = FormElements.AllKeys
         For Counter1 = 0 To Keys.GetUpperBound(0)
            Message.Text &= "Form " & Counter1 & " name: " & _
               Keys(Counter1) & "<br/>"
            Message.Text &= "Form " & Counter1 & " value: " & _
               FormElements(Counter1) & "<br/>"
         Next Counter1
      End If 
   Else
      Form1.Visible = True
   End If 
End Sub
  
<!-- This section resides between the <body> and </body> tags -->
<form id="Form1" runat="server">
   First Name: 
   <br/>
   <asp:Textbox id="txtFName" runat="server"/>
   <br/>
   Last Name: 
   <br/>
   <asp:Textbox id="txtLName" runat="server"/>
   <br/>
   <asp:Button id="Submit" Text="Submit" runat="server"/>
</form>
<asp:label id="Message" runat="server"/>

Notes

The Form collection exposes the same properties and methods described in Section 16.3 and adds the following methods:

Get(Index|Key)

Returns the contents of the specified item in the NameValueCollection as a comma-delimited String.

GetValues(Index|Key)

Returns the contents of the specified item in the NameValueCollection as a String array.

Headers

NameValueCollection = Request.Headers

The Headers collection returns an instance of the NameValueCollection class containing all HTTP headers sent with the current request. This collection provides the same information that is returned by calling the Request.ServerVariables collection with the ALL_HTTP key.

Parameter

NameValueCollection

An Object variable of type NameValueCollection.

Example

The example writes the HTTP headers passed with the request to the browser, first by using the ServerVariables("ALL_HTTP") method and then by using the Headers collection:

Sub Page_Load( )
   Dim AllHttp As String
   ' Get a String with all the HTTP headers
   AllHttp = Request.ServerVariables("ALL_HTTP")
   ' Use Replace to format the String
   AllHttp = Replace(AllHttp, "HTTP", "<br/>HTTP"
   Message.Text &= AllHttp & "<br/><br/>"
  
   Dim Counter1, Counter2 As Integer
   Dim Keys( ), subKeys( ) As String
   Dim HeaderColl As NameValueCollection
  
   ' Load Headers into NameValueCollection
   HeaderColl=Request.Headers
   ' Get keys into an array
   Keys = HeaderColl.AllKeys
   For Counter1 = 0 To Keys.GetUpperBound(0)
      Message.Text &= "Key: " & Keys(Counter1) & "<br/>"
      ' Get all values under this key
      subKeys = HeaderColl.GetValues(Counter1) 
      For Counter2 = 0 To subKeys.GetUpperBound(0)
         Message.Text &= "Value " & CStr(Counter2) & ": " & _
            subKeys(Counter2) & "<br/>"
      Next Counter2
   Next Counter1
End Sub

Notes

The Headers collection returns only the HTTP headers that were sent as a part of the current request, as opposed to the ServerVariables collection (described later in this section), which contains keys for every HTTP header, regardless of whether a value was passed.

If all you need to do is write the HTTP headers to a file or display them in the browser, it may be simpler to use the ServerVariables collection. In cases when you need to access a specific HTTP header by name or loop through the collection, the Headers collection is the way to go.

Params

NameValueCollection = Request.Params

The Params collection returns an instance of the NameValueCollection class containing key/value pairs for the QueryString, Form, ServerVariables, and Cookies collections. You can use the Params collection to dump all of these collections to a file or to the browser and to troubleshoot an application or track the form values your application receives, regardless of whether they come via GET (QueryString collection) or POST (Form collection).

Parameter

NameValueCollection

An Object variable of type NameValueCollection.

Example

The example writes the keys and values contained in the Params collection to the browser:

Sub Page_Load( )
   Dim Counter1, Counter2 As Integer
   Dim Keys( ), subKeys( ) As String
   Dim ParamColl As NameValueCollection
  
   ' Load Params into NameValueCollection
   ParamColl=Request.Params
   ' Get keys into an array
   Keys = ParamColl.AllKeys
   For Counter1 = 0 To Keys.GetUpperBound(0)
      Message.Text &= "Key: " & Keys(Counter1) & "<br/>"
      ' Get all values under this key
      subKeys = ParamColl.GetValues(Counter1) 
      For Counter2 = 0 To subKeys.GetUpperBound(0)
         Message.Text &= "Value " & CStr(Counter2) & ": " & _
            subKeys(Counter2) & "<br/>"
      Next Counter2
      Message.Text &= "<br/>"
   Next Counter1
End Sub

The following code can be used to post to the example page:

<html>
   <head>
      <title>Submit a named parameter via POST</title>
   </head>
<body>
   <form id="form1" action="Params.aspx" method="POST">
      <h3>Name:</h3>
      <input type="text" name="name">
      <input type="submit">
   </form>
</body>
</html>

Notes

The collections are listed in the following order:

  • QueryString

  • Form

  • Cookies

  • ServerVariables

While it is possible to have both the Form and QueryString collections populated (for example, if a query string name/value pair is added to the URL for the action attribute of a form by using the POST method), you will normally see one or the other, not both.

QueryString

NameValueCollection = Request.QueryString

The QueryString collection returns an instance of the NameValueCollection class containing all the keys and values passed as a part of the query string (typically by submitting an HTML form that uses the GET method instead of POST).

Parameters

NameValueCollection

An Object variable of type NameValueCollection.

Example

The example writes the contents of the QueryString collection to the browser:

Sub Page_Load( )
   Dim Counter1, Counter2 As Integer
   Dim Keys( ), subKeys( ) As String
   Dim QSColl As NameValueCollection
  
   ' Load QS into NameValueCollection
   QSColl=Request.QueryString
   ' Get keys into an array
   Keys = QSColl.AllKeys
   For Counter1 = 0 To Keys.GetUpperBound(0)
     Message.Text &= "Key: " & Keys(Counter1) & "<br/>"
     subKeys = QSCol1.GetValues(Counter1) 'Get all values under this key
     For Counter2 = 0 To subKeys.GetUpperBound(0)
        Message.Text &= "Value " & CStr(Counter2) & ": " & _
           subKeys(Counter2) & "<br/>"
     Next Counter2
     Message.Text &= "<br/>"
  Next Counter1
End Sub

The following code can be used to post to the example page (note that the form method attribute has been set to GET, which is required for the form value to be sent as part of the query string):

<html>
   <head>
      <title>Submit a named parameter via POST</title>
   </head>
<body>
   <form id="form1" action="QueryString.aspx" method="GET">
      <h3>Name:</h3>
      <input type="text" name="name">
      <input type="submit">
   </form>
</body>
</html>

Notes

One advantage that the QueryString collection has over the Form collection is that you do not always need to have the user submit a form to use it. Because the query string values are appended to the URL, it is relatively simple to statically add query strings to links within pages or dynamically create anchor tags with query string values appended. In fact, many online stores use this method to drive their catalog pages (by passing a product ID appended onto a link to the page designed to display the product). That page can then retrieve the ID by using the QueryString collection.

Because query string values are passed as plain text appended to the URL, they are more vulnerable to tampering than values passed as a result of a POST operation. If you need to pass important data or data that, if tampered with, could create problems for your application, you should consider encrypting values before adding them to the query string or using another method to pass the values.

Certain characters used in query string processing, including &, ?, %, and +, must be encoded to avoid confusion between their use in your key/ value pair and their role as special characters in a query string. The following table lists the encoding for each of these special characters:

Character

Encoding

&

%26

?

%3f

%

%25

+

%2b

Space

%20

Rather than memorizing these values, you could make your life easier by simply using the UrlEncode method provided by the HttpServerUtility class (covered in Chapter 18), which automatically substitutes the appropriate encoding for any special characters in a string passed to it.

ServerVariables

NameValueCollection = Request.ServerVariables

Parameter

NameValueCollection

An Object variable of type NameValueCollection.

Example

The example, as in the previous collection-related examples, writes the contents of the ServerVariables collection to the browser:

Sub Page_Load( )
   Dim Counter1, Counter2 As Integer
   Dim Keys( ), subKeys( ) As String
   Dim SVarsColl As NameValueCollection
  
   ' Load ServerVariables into NameValueCollection
   SVarsColl=Request.ServerVariables
   ' Get keys into an array
   Keys = SVarsColl.AllKeys
   For Counter1 = 0 To Keys.GetUpperBound(0)
      Message.Text &= "Key: " & Keys(Counter1) & "<br/>"
      subKeys = SVarsColl.GetValues(Counter1) 
      ' Get all values under this key
      For Counter2 = 0 To subKeys.GetUpperBound(0)
         Message.Text &= "Value " & CStr(Counter2) & ": " & _
            subKeys(Counter2) & "<br/>"
      Next Counter2
      Message.Text &= "<br/>"
   Next Counter1
End Sub

Notes

In addition to retrieving all the values by looping through the keys, you can access individual values if you know their key. The following list shows the available keys for the ServerVariable collection:

ALL_HTTP

Returns a string containing all HTTP headers with each header name taking the form HTTP_headername, for which headername is the name of an HTTP header in all capital letters.

ALL_RAW

Provides the same information as ALL_HTTP, but header names are not all capital letters and are not prefixed with HTTP_.

APPL_MD_PATH

Returns the path of the application in the IIS metabase.

APPL_PHYSICAL_PATH

Returns the physical path that corresponds to APPL_MD_PATH.

AUTH_TYPE

Returns the authentication method used to validate access to protected content.

AUTH_USER

Returns the username of the authenticated user in raw form.

AUTH_PASSWORD

Returns the password entered in the browser's authentication dialog, assuming Basic authentication was used.

LOGON_USER

Returns the name of the Windows account the current user is logged in to.

REMOTE_USER

Returns the username string sent by the browser before any authentication filtering has taken place.

CERT_COOKIE

Returns a unique string identifier for the client certificate.

CERT_FLAGS

Returns bit flags that represent whether a certificate is present (bit0) and whether the certificate authority for the client certificate is in the list of recognized certificate authorities on the server (bit1).

CERT_ISSUER

Returns the issuer of the client certificate.

CERT_KEYSIZE

Returns the number of bits for the SSL key (e.g., 40 or 128).

CERT_SECRETKEYSIZE

Returns the number of bits in the server's private key.

CERT_SERIALNUMBER

Returns the serial number of the client certificate.

CERT_SERVER_ISSUER

Returns the issuer of the server certificate.

CERT_SERVER_SUBJECT

Returns the subject field of the server certificate.

CERT_SUBJECT

Returns the subject field of the client certificate.

CONTENT_LENGTH

Returns the length of the content in the body of the HTTP request.

CONTENT_TYPE

Returns the MIME type of the content in the HTTP request.

GATEWAY_INTERFACE

Returns the revision number of the CGI specification used by the server.

HTTPS

Returns either on or off, depending on whether the request came through a secure socket (HTTPS) connection.

HTTPS_KEYSIZE

Returns the size, in bits, of the SSL key.

HTTPS_SECRETKEYSIZE

Returns the number of bits in the server's private key.

HTTPS_SERVER_ISSUER

Returns the issuer of the server certificate.

HTTPS_SERVER_SUBJECT

Returns the subject field of the server certificate.

INSTANCE_ID

Returns the ID for the IIS instance associated with the request. Unless more than one instance of IIS is running, this value is always 1.

INSTANCE_META_PATH

Returns the metabase path to the instance of IIS that responds to the current request.

LOCAL_ADDR

Returns the server address on which the request was received. Useful for servers with multiple NICs and IP addresses to determine which address received the request.

PATH_INFO

Returns any extra path information passed with the request. See the PathInfo property earlier in the chapter for more information.

PATH_TRANSLATED

Returns the physical path corresponding to the virtual path for the request.

QUERY_STRING

Returns the raw query string (if any) passed with the request.

REMOTE_ADDR

Returns the IP address of the machine making the request.

REMOTE_HOST

Returns the DNS name of the machine making the request, if available. Otherwise, returns the IP address.

REQUEST_METHOD

Returns the HTTP request method (GET, POST, etc.) used in the request.

SCRIPT_NAME

Returns a virtual path to the page being executed.

SERVER_NAME

Returns the server name, DNS name, or IP address of the server.

SERVER_PORT

Returns the port number on which the request was received.

SERVER_PORT_SECURE

Returns a string containing either 0 or 1, depending on whether the request was received on a secure port (1) or not (0).

SERVER_PROTOCOL

Returns the name and version of the protocol used to handle the client request. For IE 5.5 and IIS 5, this name and version would be "HTTP/1.1".

SERVER_SOFTWARE

Returns the name and version of the web server software.

URL

Returns the base URL of the request (i.e., everything after the domain name).

HTTP_CONNECTION

Returns the type of connection established.

HTTP_ACCEPT

Returns the value of the HTTP Accept header.

HTTP_ACCEPT_ENCODING

Returns the value of the HTTP Accept-Encoding header.

HTTP_ACCEPT_LANGUAGE

Returns the value of the HTTP Accept-Language header.

HTTP_HOST

Returns the value of the HTTP Host header.

HTTP_USER_AGENT

Returns the value of the HTTP User-Agent header.

      Previous Section Next Section