The first topic in this chapter explained that when ASP.NET processes a Web page, it does so in several phases. By raising events, ASP.NET makes it easy to integrate your own code with these phases. The table on the next page shows the most common Page events that occur during a normal life cycle. If you want ASP.NET to run some code when any of these events occur, simply define a subroutine with the name Page followed by an underscore and the name of the event. Here’s an example:

Sub Page_Load(Sender As Object, E As EventArgs)
'    Your code goes here.
End Sub

As with all subroutine definitions, this one must appear within <script runat="server"> and </script> tags. Only the subroutine name is important, not its location within the page.

Page_Init occurs before ASP.NET loads all the runat="server" tags into memory. Since most code you write will deal with these objects, the Page_Init event might not be terribly useful.

This event does have the advantage of running before any subroutines that respond to events on the browser. If you need to open a database connection or some other resource before those event handlers run, a Page_Init subroutine might be the place to put them.

Page_Load is generally the most useful and most often used event. This event occurs after the page is fully loaded, but before ASP.NET starts creating HTML.

Page_PreRender occurs after Page_Load and before ASP.NET starts creating HTML. In most cases it’s easier to put code at the end of the Page_Load routine than to set up a Page_PreRender subroutine, but the choice is yours.

Page_Unload occurs after ASP.NET has finished creating HTML. This event is usually too late to do anything useful, except possibly to close resources. Because most programmers close resources after the last statement that uses them, this event doesn’t see much use.

Page_Error provides a final opportunity to execute code before ASP.NET sends the visitor its standard error page. Here you can put any special error-handling code you want, such as putting messages in the system Event log or sending yourself an e-mail.

In addition to its other talents, the Page object also provides a number of useful methods. Many of these are useful only at a very low, obscure level, but two deserve special mention: MapPath and ResolveUrl.

MapPath translates a virtual path, either absolute or relative, to a physical path. That is, it converts a URL on the local server to a physical file path. Consider the following statement:

strPhysPath = MapPath("/")

After executing this statement, the strPhysPath variable would typically return C:InetPubwwwroot. Here’s another example:

strPhysPath = MapPath("/webdbpgm/ch03/default.htm")

This code would typically return C:InetPubwwwrootch03default.htm. This sort of information is quite useful when you know only the URL of a file or folder, but some method or API requires a physical file name.

ResolveUrl converts a relative URL to a fully qualified URL on the local server, based on the location of the current Web page. If, for example, the URL path to the current Web page is /webdbpgm/ch03/resolve.aspx, you could execute this statement:

strURL = ResolveURL("../images/classad-l.gif")

This statement would store the value /webdbpgm/images/classad-l.gif in the variable strURL.

In addition to providing essential built-in events, the Page object provides a wealth of useful properties. The tables in Demonstrate ASP.NET page events and Demonstrate ASP.NET page events list the properties ASP.NET developers are most likely to use.

To contradict an earlier statement, most developers aren’t likely to make direct use of the Controls property very often. However, existence of this property is relevant to the @ Reference directive described later in this chapter.

The Cookies collection contains name=value pairs for any cookie values that the Web page sends. To send the visitor a cookie as part of an out-going Web page, code

Response.Cookies("myName") = strMyValue

where myName is any name you choose and strMyValue is an arbitrary variable or literal. The browser will then return the cookie the next time it requests the page. To retrieve the cookie value, code

strMyValue = Request.Cookies("myName")

Notice that you send the cookie through the Response object and retrieve it through the Request object. This action makes complete sense given the usual role these objects play.

Use of the IsPostBack property pertains to Web Forms, a facility which the next chapter describes. The property is False for the first display of a form, and True for the second and all successive submissions of the same form.

The IsValid property pertains to Validation Server Controls. These are ASP.NET page elements that check fields on a Web Form for correct syntax. If no Validation Server Controls detect an error, the IsValid property is True. If one or more such controls detect an error, IsValid is False.

The Trace property points to an object that displays debugging data. More information about this facility will appear later in the chapter, but for now, adding the attribute Trace="True" to the @ Page directive shown below displays a variety of information about the execution of the current Web page.

<%@ Page Language="VB" Debug="True" Trace="True" %>

The User property provides the identity of the current Web visitor, but only if you require that your visitors go through a logon procedure. For more information about requiring and validating user identities, refer to Chapter 11.

Like the IsPostBack and IsValid properties, the ViewState property applies only to Web Forms. Basically, it provides a list of name=value pairs that you can send out with a form and then receive back with the next submission. ASP.NET uses this same facility to store the value of text boxes, drop-down lists, and other form elements.

As shown in the table below, the Page object also provides ASP.NET versions of the five major objects that classic ASP used for communicating with the Web server.

The next three sections will describe the Request, Response, and Server objects. A later chapter (Chapter 11) discusses the Application and Session objects.

The Page.Request object contains information about the request that triggered the Web page. In a sense, it answers the questions "Why am I here?" and "What am I supposed to do?" The next table lists the properties that the Request object provides.

Several Request object properties warrant additional mention. Two of these are Request.Form and Request.QueryString.

The Request.Form property contains a collection of values the browser transmitted from an HTML form that uses the POST method. Likewise, the Request.QueryString property contains a collection of values the browser transmitted from an HTML form that uses the GET method.

Assuming that only one value exists for a given name, the syntax for retrieving a value is unchanged from classic ASP. The following example obtains the value of the form field identified in the HTML as quantity and stores it in a variable named strQty:

strQty = Request.Form("quantity")

In this example, quantity is the form field’s name as coded in the HTML.

If two or more values with the same name exist in the same collection, the expression just shown returns all the values in a comma-delimited list. This works the same way in ASP.NET as it did in classic ASP.

A discrepancy exists if the collection contains two or more items with the same name and you wish to retrieve them individually. In classic ASP, you would access the first two values using statements like these:

strQty1 = Request.Form("quantity")(1)
strQty2 = Request.Form("quantity")(2)

In ASP.NET, retrieving the same two values requires this code:

strQty1 = Request.Form.GetValues("quantity")(0)
strQty1 = Request.Form.GetValues("quantity")(1)

Similar considerations apply to the QueryString, Cookies, ClientCertificate, and ServerVariables collections.

Another difference between classic ASP and ASP.NET affects the syntax for searching several collections at once. In classic ASP, you could code

strQty = Request("quantity")

and ASP would search the QueryString, Form, Cookies, ClientCertificate, and ServerVariables collections—in that order—until it found a value named quantity. This still works, but the following expression is preferable:

strQty = Request.Params("quantity")

Params is a single collection that incorporates all items in the QueryString, Form, ServerVariables, and Cookies collections. Using the Params collection is more efficient than searching the five individual collections. In addition, because Params is a real collection, you can process it with constructs like For Each...Next loops.

As Chapter 4 will explain in much greater detail, the Web Forms feature of ASP.NET provides a newer and much more powerful way for forms on the browser and code on the server to interact. Although the Request.Forms and Request.QueryString collections are still a part of ASP.NET, Web Forms will largely eliminate their presence in most forms-processing Web pages.

Both classic ASP and ASP.NET provide information about the Web visitor, the visitor’s browser, the Web server, and other details of a particular transaction in the Request.ServerVariables collection. The following expression, for example, copies the exact URL that the visitor requested into a variable named strUrl:

strURL = Request.ServerVariables("url")

Although ASP.NET still supports such expressions, it now provides direct property support for the same variables. The following statement, for example, is much more direct and uses fewer resources than the previous one:

strURL = Request.Url

The easiest way to view the contents of the QueryString, Cookies, ClientCertificate, and ServerVariables collections is to request a trace of the Web page. To do this, add the following statement at the beginning of your .aspx file:

<%@ Page Trace="True" %>

If the page already contains an @ Page directive, simply add the directive Trace="True". For more information about the @ Page directive, refer to "Coding the @ Page Directive" later in this chapter.

Requesting a trace tells ASP.NET to collect a variety of useful information and display it at the bottom of the output Web page. Unless the QueryString, Cookies, ClientCertificate, and ServerVariables collections are empty, you’ll find them clearly listed under prominent headings. This graphic shows some typical trace output.

Curiously, the ASP.NET trace display doesn’t show the contents of the Request.Form collection. If you’re using Web Forms, however, the value of each form field appears in the Control Tree section of the trace. For more information about using the Trace facility for debugging, refer to Chapter 15.

As alter ego to the Request object, the Response object transmits the output Web page to the visitor who submitted a request. Most of its many features are seldom used and deserve only minimal coverage in this section. Nevertheless, listings of the Response object’s properties and methods appear in the tables in Working with HTML Server Control Attributes and Retrieving HTML Server Control Form Field Values.

For more information on how to send and receive cookies, refer to "Using the Cookies collection" earlier in this chapter.

The Response.Buffer property is a True/False switch that tells the Web server whether to delay transmitting the outgoing Web page until rendering is complete. This decision requires certain resources from the Web server, but if code that runs during rendering modifies headers or other information at the beginning of the Web page, buffering is the only option.

The Response.Clear method erases the buffer. Use of this method is rare.

The Response.Flush method immediately transmits any rendered HTML that currently resides in the output buffer—a step that’s sometimes useful when the Web page takes a long time to run and you want to release the page banner or other fast-running content without waiting for output from the long-running process. However, this works only if you put the long-running code inside code render blocks located after the Response.Flush statement. Code invoked by custom or built-in events—such as the Page_Load event—always runs to completion before page rendering starts.

The ContentType property controls a header field that tells the browser what kind of output you’re sending. The default, of course, is text/html. If your code is generating something other than HTML—plain text, Extensible Markup Language (XML), or pictures, for example—you’ll need to modify this property to text/plain, text/xml, image/gif, image/jpeg, or whatever is appropriate. For examples of ASP.NET pages that create GIF and JPEG pictures, refer to Chapter 8.

Because the ContentType property modifies a header field, you must change it either before rendering the opening <html> tag or, as just described, with buffering in effect.

To control how long a Web visitor’s browser can cache a page, modify the page’s Response.Expires or Response.ExpiresAbsolute property. Response.Expires specifies a number of minutes, while Response.ExpiresAbsolute specifies a date and time. Setting Response.Expires to zero tells the browser it should request a fresh copy of the page every time the Web visitor views it. This is another HTTP header field and requires the same precautions as the ContentType property.

This, however, is an outdated technique preserved for compatibility with classic ASP. The @ OutputCache directive described later in this chapter is far more powerful and fully up to date.

Response.Status specifies a three-digit status code followed by one space and then a brief text message. The default value is "200 OK" but you can modify this to values such as "401 Unauthorized" or "301 Moved Permanently." A 401 status code tells the browser to prompt the Web visitor for a user name and password and then resubmit the request. Combined with a Response.Redirect value (described below), a 301 status code tells the browser to automatically redirect all future requests. This is another header field and requires the usual precautions (that is, buffering or placement before the first HTML or Response.Write statement).

The following table describes the methods that the Response object provides:

The Response.AddHeader method adds any header information you want to the outgoing Web page. Headers consist of a text identification string, a colon, a space, and then a value. Obviously, the browser must understand any header you send; otherwise the browser ignores it. And, of course, the usual precautions regarding the timing of headers apply.

The Response.End method tells the Web server to stop processing the ASP page immediately. The Web server will send the Web visitor any output you created prior to invoking the Response.End method.

The Response.Redirect method sends the Web visitor to another URL that you specify as an argument. For example, coding

Response.Redirect "/default.htm"

sends the Web visitor to the server’s home page. If you specify a URL on the same Web server as the ASP page, the server simply abandons the current request and delivers the redirect page instead. If you specify a URL on a different server, the current server sends the browser a message that tells it to contact the other server. The usual precautions for modifying header fields apply.

Last but not least, the Response.Write statement sends the Web visitor any string you specify as an argument. The characters sent can be HTML, data, JavaScript, or anything else the browser understands. This book has already shown you many examples of the Response.Write statement and will show you many more.

Unlike the Request and Response objects, which receive data from and send information to the Web visitor, the Server object doesn’t involve communicating over the network. Instead, it provides an interface between your code and the Web server that runs it. The Server object contains two properties: MachineName and ScriptTimeout.

The MachineName property gets and displays the name of the computer where the Web server is running. To display this name on the Web server’s console:

The ScriptTimeout property specifies how many seconds the Web page can run before the server terminates it. An administrator configures the default ScriptTimeout value at the server level, but it’s usually 90 seconds. ASP.NET code can lengthen (but not shorten) this interval.

The following table summarizes the methods that the Server object provides:

The CreateObject method creates any COM objects your ASP page requires. Code this method as follows:

variable = Server.CreateObject("ADODB.Recordset")

The Server.CreateObjectFromClsid method performs the same function, except that its argument is a Class ID. Here’s an example:

variable = _
Server.CreateObjectFromClsid("00000514-0000-0010-8000-00AA006D2EA4")

These two methods apply only to COM objects. To instantiate a .NET object, use a Dim statement or the New keyword as shown in the two following examples:

Dim cnAds As OleDbConnection
cnAds2 = New OleDbConnection

The HTMLEncode method examines a string argument, replaces any special characters with their HTML mnemonic equivalents, and returns the result. For example, any ampersands in the argument appear as &amp; any quotation marks as &quot; and so on. The HTMLDecode method reverses this translation.

The URLEncode method performs a different kind of conversion: it converts any argument you give it to a string suitable within a URL. Here are the rules:

The URLDecode method does the reverse.

The Execute method runs another Web page and receives the results through a StringWriter object. Consider the following example:

Dim writer As New StringWriter
Server.Execute("otherpage.aspx", writer)
Response.Write("<p>The other page contains:</p>" & _
    writer.ToString())

Line 1 creates a StringWriter. Line 2 runs the otherpage.aspx file, directing its output into the StringWriter object. Line 3 writes a header line followed by the contents of the StringWriter object (expressed as a string) into the Response object for transmission to the Web visitor.

The Transfer method stops execution of the current page and starts executing another page in its place. The Web visitor receives the output of the second page. If you code

Server.Transfer("surrogate.aspx")

the visitor will receive the output of the surrogate.aspx page as if he or she typed that URL into the browser’s Address field. If you want the specified page to receive the current page’s Form and QueryString collections, code

Server.Transfer("surrogate.aspx", True)

The @ Page directive appears in more ASP.NET pages than any other. Here are its most frequently used attributes:

The @ Import directive approaches or exceeds the @ Page directive in popularity, depending on how you count. It makes all the classes and interfaces of a given namespace available to the page that contains the directive. The given namespace can be part of the .NET Framework class library or a user-defined namespace. To code this directive, enter

<%@ Import namespace=" value" %>

where value is the name of the namespace you want to import. A given @ Import directive can specify only one namespace. To import several namespaces, code a separate @ Import directive for each one.

The need to import a namespace usually becomes apparent when you try to use a certain object and receive a "Type is not defined" message. Suppose, for example, that you coded

Dim fviFileVers As FileVersionInfo

Now suppose that you tried to run the page, and got the following compiler message:

BC30002: Type is not defined: 'FileVersionInfo'

To solve this, you would look up the documentation for the FileVersionInfo object (perhaps by searching MSDN for the keywords FileVersionInfo and Framework) and discover that it’s part of the System.Diagnostics namespace. Voil ! Adding the following directive at the top of the page will get rid of the error message:

<%@ Import Namespace="System.Diagnostics" %>

After a while, you’ll no doubt start remembering which namespaces your favorite classes (that is, your favorite object types) require and coding the necessary import directives as a matter of habit. You’ll also start paying attention to and importing the namespaces of other objects you locate to perform specific tasks. In this regard, it’s helpful to know that every ASP.NET page automatically imports the namespaces listed here with no code or effort from you.

This directive controls the output caching policies of an ASP.NET page or a user control contained in a page. Here’s the required syntax:

<%@ OutputCache
    Duration="#ofseconds"
    Location="Any | Client | Downstream | Server | None"
    VaryByCustom="browser | customstring"
    VaryByHeader="headers"
    VaryByParam="parametername" %>

The following list describes the acceptable values for each @ OutputCache attribute.

The following example caches the page on the server for 10 seconds. If any visitor causes this page to run, and then another request arrives within 10 seconds, the server will send a cached copy of the first results rather than running the page again.

<%@ OutputCache Duration="10"
                Location="Server"
                VaryByParam="none" %>

The next example caches a different version of the output for each combination of values in the location and count form fields. If two or more requests that specify the same location and count values arrive within 10 seconds, the second and all subsequent visitors will received a cached copy of what the first visitor received.

<%@ OutputCache Duration="10"
                Location="Server"
                VaryByParam="location;count" %>

The @Control directive serves the same function for user controls (.ascx files) that the @ Page directive serves for pages (.aspx files). It supports all the same attributes as the @ Page directive, except for AspCompat and Trace. These two attributes apply to an entire page and not just to one control.

The @ Implements directive is another directive that’s valid only within an .ascx file—that is, a file that defines a user control. It tells ASP.NET that the control has, and is willing to accept, the properties, methods, and events of a specified .NET Framework interface.

Suppose, for example, that you want to create a user control that captures form information submitted from the browser. ASP.NET provides this information to a user control by calling an interface named System.Web.UI.IPostBackEventHandler. The .ascx file that contains the user control’s code must therefore contain the following directive:

<%@ Implements Interface="System.Web.UI.IPostBackEventHandler" %>

Of course, the .ascx file must also support all the properties, methods, and events that the System.Web.UI.IPostBackEventHandler expects. Whoever develops the user control code must understand what these are and provide the necessary code.

When coding is complete, other pages can use the user control by coding an @ Register directive (described shortly) in the usual way. The @ Register directive tells ASP.NET to load the .ascx file, and in so doing ASP.NET notices the @ Implements directive. Thereafter, when a System.Web.UI.IPostBackEvent occurs for the given user control, ASP.NET will invoke the interface code that the developer provided.

Use of the @ Implements directive is a fairly advanced technique. Most use of form input and custom controls is drastically simpler.

The @ Register directive identifies the source file or assembly that contains the code for a user control. If the code resides in a source file, the @ Register directive must look like this:

<%@ Register tagprefix=" tagprefix"
             Tagname=" tagname"
             Src=" pathname" %>

To visualize how this works, imagine that you have a user control in a file named cscsrules.ascx and that it consists entirely of this line of code:

<p>User controls rule.</p>

Now suppose that you coded the following @ Register directive in a page:

<%@ Register tagprefix="myTags" Tagname="rule"
             Src="cscsrules.ascx" %>

Within that page, <p>User controls rule.</p> appears wherever you coded the following tag:

<myTags:rule id="ruleTag" runat="server" />

Most user controls, of course, do much more work than just displaying static HTML. They have properties you can read and write in all the usual ways—including attributes you code within the tag—and they have code that customizes the output HTML based on property values, the type of browser, database values, or anything else you can imagine. For more information about user controls, refer to Chapter 9.

Here’s the second form of the @ Register directive:

<%@ Register TagPrefix=" tagprefix"
             Namespace=" namespace"
             Assembly=" assembly" %>

This form assigns a tag prefix and a namespace identifier to all controls in a given assembly. An assembly is a .dll or .exe file that contains one or more controls. You can create assemblies directly in Visual Studio .NET, or you can compile the source files and combine them into assemblies using command line utilities that come with the .NET Framework. To learn more about this process, search the MSDN Web site (msdn.microsoft.com/library) for the terms Building a SingleFile Assembly and Building a Multifile Assembly.

In the following example, the @ Register directive declares myTag as a tag prefix and myCompany:myNameSpace as a namespace for all controls residing in the assembly named myAssembly:

<%@ Register Tagprefix="myTag"
             Namespace="myCompany:myNameSpace"
             Assembly="myAssembly" %>

If this assembly contained a control named myControl, the following tag would display an instance of it:

<myTag:myControl id="Control1" runat="server" />

The issue of where to physically locate the assembly files is a surprisingly complex topic. The most direct approach is to simply put them in a bin folder located at the application root. However, in the application’s web.config file you can specify additional paths to search, even including locations on the Web. Finally, you can put assemblies anywhere you want and then assign them to a global cache that makes them available to every application on the local machine.

This book makes very little use of assemblies.

The @ Assembly directive links an assembly to the current page during compilation, which makes all the assembly’s classes and interfaces available for use. There are two forms to this directive, the first of which is

<%@ Assembly Src="pathname" %>

This form specifies the path and file name of a source file that ASP.NET will compile along with the rest of the page. The following statement, for example, makes any classes and interfaces defined in the Visual Basic .NET source file mySource.vb available to the current page:

<%@ Assembly Src="mySource.vb" %>

The second form specifies the name of a compiled assembly:

<%@ Assembly Name=" assemblyname" %>

Note that this form specifies no path and no filename extension. Instead, it searches for the application in the same way as the assembly= form of the @ Register directive. The following example links to a precompiled assembly named myAssembly:

<%@ Assembly Name="myAssembly" %>

Precompiled assemblies that reside in your Web application’s bin directory are automatically linked to pages within that application and don’t require an @ Assembly directive.

You can’t specify both the Name attributes and the Src attributes in the same @ Assembly directive. To use both, you must code two directives.

If the difference between the @ Register directive and the @ Assembly directive seems obscure, consider this:

The classtest.aspx page in the ch03 folder of the sample files on the companion CD uses an @ Assembly directive to make a class named Biology available to the Web page. The Biology class itself resides in a file named biology.vb.

The @Reference directive indicates that ASP.NET should dynamically compile and link the source file for another user control or page against the page that contains the directive. There are two forms:

Any page or user control you compile through this directive becomes a member of the ControlCollection object—which you can access through the Controls property—for the page or server control. After calling the LoadControl method (which the page inherits from the TemplateControl class), you can cast the returned type.

The following example links a page to a user control, myControl.ascx. Using the LoadControl method, it then loads the control to a containing page. Next, the example sets the control’s myProperty value and adds it, through the Controls property, to a PlaceHolder control’s ControlCollection object.

<%@ Reference Control="myControl.ascx" %>
<script language="VB" runat=server>
Sub Page_Load(sender As Object, e As EventArgs)

  Dim myControl As myControl = _
    CType(Page.LoadControl("myControl.ascx"), myControl)
  myControl.myProperty = "Color"

  PlaceHolder.Controls.Add(myControl)
End Sub
</script>

<html>
<body>
    <asp:placeholder id="PlaceHolder" runat=server/>
</body>
</html>