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

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.

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.

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.

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.

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.

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.

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:

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.

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.