Overview

The nice thing about being a celebrity is that when you bore people, they think it's their fault.

-Henry Kissinger

In Chapter 2, I described in detail the various steps that take an incoming HTTP request to be served by the ASP.NET worker process. I'll summarize the process here. The request is assigned to the aspnet_isapi.dll ISAPI extension which, in turn, hands it over to the HTTP runtime pipeline. A new instance of the HttpRuntime class is created for each request and governs its overall execution. The HttpRuntime class represents the entry point in the ASP.NET pipeline that will generate the response text for the browser. Upon instantiation, the HttpRuntime class performs a number of initialization tasks, the first of which is the creation of a wrapper object to encapsulate all the HTTP-specific information available about the request. The newly created object—an instance of the HttpContext class—is then passed along to the pipeline and is used by the various modules to access intrinsic worker objects such as Request, Response, and Server.

In this chapter, we'll first review the startup process of the ASP.NET application and then move on to examine the various objects that form the context of the HTTP request. If you're a former ASP developer, the contents of this chapter might sound familiar as we discuss old acquaintances such as Request, Response, and Server. However, you need to notice up front that the role of these intrinsic ASP objects is different in ASP.NET. They are fully supported and fully backward-compatible with ASP, but their functionality is built on top of a completely redesigned server architecture.

Initialization of the Application

Once you've created the context for the request, the HttpRuntime class sets up an ASP.NET application object to carry out the request. An ASP.NET application consists of an instance of the HttpApplication class that we briefly discussed in Chapter 2. HttpApplication is a global.asax-derived object that handles all HTTP requests directed to a particular virtual folder.

An ASP.NET running application is wholly represented by its virtual folder and optionally by the global.asax file. The virtual folder name is a sort of key the HTTP runtime uses to selectively identify which of the running HttpApplication objects should take care of the incoming request. The global.asax file, if present, contains code for responding to application-level events raised by ASP.NET or by registered HTTP modules that affect the application. Figure 13-1 shows a detailed view of the process that creates a page for a request. You'll see that requests pass through the application factory that picks up (or creates) a valid HttpApplication object from a pool. The HttpApplication object, in turn, selects the proper resource handler based on the type of the request (.aspx, .asmx, or other type).

Figure 13-1: The process of creating a page for an HTTP request.

The particular HttpApplication selected is responsible for managing the entire lifetime of the request it is assigned to. That instance of HttpApplication can be reused only after the request has been completed. If no HttpApplication object is available, either because the application has not been started or all valid objects are busy, a new HttpApplication is created and pooled.

Properties of the HttpApplication Class

Although the HttpApplication class provides a public constructor, user applications never need to create instances of the HttpApplication class directly. The ASP.NET runtime infrastructure always does the job for you. As mentioned, instances of the class are pooled and, as such, can process many requests in their lifetime (but always one at a time). Should concurrent requests arrive for the same application, additional instances are created. Because the HttpApplication object serves just one request at a time, its member variables store per-request data. Table 13-1 lists the properties defined on the class.

A good question at this point of the discussion would be the following. Because the HttpApplication class is managed by the ASP.NET infrastructure, how can I take advantage of the fairly rich, public programming interface of the class? Properties, overridable methods, and class events, can be accessed and programmatically manipulated in the global.asax file. (We'll return to global.asax later in the section "The global.asax File.")

Application Modules

The Modules property returns a collection of applicationwide components providing ad hoc services. An HTTP module component is a class that implements the IHttpModule interface. Modules can be considered the managed counterpart of ISAPI filters; they are a kind of request interceptor with the built-in capability of modifying the overall context of the request being processed. The .NET Framework defines a number of standard modules as listed in Table 13-2. Custom modules can be defined too. We'll cover this particular aspect of HTTP programming in Chapter 23.

The list of default modules is defined in the machine.config file and can be modified to include new modules or exclude some of those shown in the preceding table. The modules listed in machine.config are available to all applications. By creating a proper web.config file, you can also create an application-specific list of modules. (See Chapter 12.)

It's worth noting that no class can be inherited. The reason is because all those classes are associated with the predefined mechanisms for authentication and authorization. Making those classes inheritable would have opened a potential security hole in ASP.NET. A derived class, in fact, often looks like the original but can provide significantly different good and bad features.

Methods of the HttpApplication Class

The methods of the HttpApplication class can be divided in two groups—operational methods and event handler managers. The HttpApplication operational methods are described in Table 13-3.

Note that Init and Dispose are quite different from well-known event handlers such as Application_OnStart and Application_OnEnd. Init executes for every request directed at the Web application, whereas Application_OnStart fires only once in the Web application's lifetime. Init indicates that a new instance of the HttpApplication object has been created to serve an incoming request; Application_OnStart denotes that the first instance of HttpApplication has been created to start up the Web application and serve its very first request. Likewise, Dispose signals the next termination of the request processing but not necessarily the end of the application. Application_OnEnd is raised only once, when the application is being shut down.

You should also be aware that all resources you create that override the Init method are shared only with the current instance of modules, and in no way are those objects visible across multiple requests. Data that must survive multiple requests should be stored in instances of global state classes such as HttpApplicationState (the property Application) or HttpSessionState (the property Session). Any resource that gets created in Init should be cleaned up in Dispose.

In addition to the operational methods in Table 13-3, a few other HttpApplication methods are available and listed in Table 13-4. These methods are of no interest to user applications and are used only by HTTP modules to hook up the events generated during the request's chain of execution. The description of all methods is identical; what really changes is the name of the event that the handlers are attached to. All methods in Table 13-4 add the specified event handlers to the collection of handlers associated with the specified asynchronous application event. Event handlers are detached when the request is completed.

You should note that there are two versions of each application event, a synchronous version and an asynchronous version. The methods listed in Table 13-4 are for the asynchronous versions.

Each module is requested to indicate a begin handler and an end handler. The following code shows the prototype of the AddOnAcquireRequestStateAsync method. Other prototypes are nearly identical.

public void AddOnAcquireRequestStateAsync( BeginEventHandler bh, EndEventHandler eh );

The BeginEventHandler is the delegate called at the start of the asynchronous event processing, while EndEventHandler is the delegate that gets into the game at the end of event processing.

Events of the HttpApplication Class

Table 13-5 describes the event model of the HttpApplication class—that is, the set of events that HTTP modules, as well as user applications, can listen to and handle.

To handle any of these events asynchronously, an application will use the corresponding method in Table 13-4. To hook up some of these events in a synchronous manner, an application will define in the global.asax file event handler procedures with the following signature:

public void Application_XXX() { // do something here }

Of course the XXX placeholder must be replaced with the name of the event. All the events in the preceding table provide no event-specific data. You could also use the following syntax:

public void Application_XXX(object sender, EventArgs e) { // do something here }

This syntax, however, doesn't give you additional information and programming power. The sender argument evaluates to the sender object, which is always the ASP.global_asax class, with a couple of exceptions. The sender is HttpApplicationFactory when the application starts up and SessionStateModule when the session is started.

In addition to the events of Table 13-5, in the global.asax file, an application can also handle Application_OnStart and Application_OnEnd. When ASP.NET is about to fire BeginRequest for the very first time in the application lifetime, it makes Application_OnStart precede it. EndRequest will happen at the end of every request to an application. Application_OnEnd occurs outside the context of a request, when the application is ending. Let's examine the order in which events are raised.

1. BeginRequest. The ASP.NET HTTP pipeline begins to work on the request. This event reaches the application after Application_OnStart.
2. AuthenticateRequest. The ASP.NET runtime has attempted to authenticate the user. All the information available is stored in the HttpContext's User property. The user name is typically set to the empty string for anonymous, unauthenticated users.
3. AuthorizeRequest. The ASP.NET runtime has attempted to verify the user's authorization to access the resource.
4. ResolveRequestCache. The ASP.NET runtime verifies whether returning a previously cached page can resolve the request. If a previously cached page cannot resolve the request, the procedure continues. An HTTP handler corresponding to the requested URL is created at this point. If the requested resource is an .aspx page, an instance of a page class is created. Note that the Session_OnStart event (which occurs when the request starts a new session) is raised only at this point, following ResolveRequestCache.
5. AcquireRequestState. The newly created HTTP handler object that will handle the request is associated with state information (such as Application, Session, and other types).
6. PreRequestHandlerExecute. This event is fired just before calling the ProcessRequest method on the handler—a Page-derived class if the request targets an .aspx resource. The handler does its job and generates the output for the client.
7. PostRequestHandlerExecute. This event is raised when the handler has generated the response text.
8. ReleaseRequestState. This event is raised when the handler releases its state information and prepares to shut down. At this point, modules registered to filter the response text have their best chance to operate. The response text hasn't been sent yet.
9. UpdateRequestCache. The ASP.NET runtime determines whether the generated output, now also properly filtered by registered modules, should be cached to be reused with upcoming identical requests.
10. EndRequest. This event fires as the final step of the HTTP pipeline. The control passes back to the HttpRuntime object, which is responsible for the actual forwarding of the response to the client. At this point, the text has not been sent yet.

Another pair of events can occur during the request, but in a nondeterministic order. They are PreSendRequestHeaders and PreSendRequestContent. The PreSendRequestHeaders event informs the HttpApplication object in charge of the request that HTTP headers are about to be sent. The event normally fires after EndRequest but not always. For example, if buffering is turned off, the event gets fired as soon as some content is going to be sent to the client. Finally, with the PreSendRequestContent event, the HttpApplication object in charge of the request learns that the response body is about to be sent.

In Figure 13-2, you can see a sample application (logevents.aspx) that uses global.asax to accumulate and display text for events as they are detected.

Figure 13-2: Logging the events raised while a request is being processed.

In all these event handlers, you can write code the same as in the context of an HttpApplication class, meaning you can access Request, Response, and Server without instance prefixes. You're just writing methods of a class that inherits from HttpApplication.

The global asax File

The global.asax file is used by Web applications to handle some application-level events raised by the ASP.NET runtime or by registered HTTP modules. The global.asax file is optional. If missing, the ASP.NET runtime environment simply assumes you have no application or module event handlers defined. To be functional, the global.asax file must be located in the root directory of the application. Only one global.asax file per application is accepted. (global.asax files placed in subdirectories are simply ignored.)

Compiling global asax

When the application is started, the global.asax file, if present, is parsed into a source class and compiled. The resultant assembly is created in the temporary directory just as any other dynamically generated assembly would be. (See Chapter 2 for more information on this procedure.) The following listing shows the skeleton of the C# code that ASP.NET generates for any global.asax file:

namespace ASP { public class global_asax : System.Web.HttpApplication { private static bool __initialized = false; // // The source code of "global.asax" file is flushed // here verbatim. For this reason, the following code // in global.asax would generate a compile error. // int i; // i = 2; // can't have statements outside methods // public global_asax() { if ((ASP.global_asax.__initialized == false)) { ASP.global_asax.__initialized = true; } } } }

The class is named ASP.global_asax and is derived from the HttpApplication base class. In most cases, you deploy global.asax as a separate text file; however, you can also write it as a class and compile it either in a separate assembly or within your project's assembly. The class source code must follow the outline shown earlier and, above all, must derive from HttpApplication. The assembly with the compiled version of global.asax must be deployed in the application's Bin subdirectory.

Note, though, that even if you isolate the logic of the global.asax file in a precompiled assembly, you still need to have a (codeless) global.asax file that refers to the assembly. (This is exactly what happens with Visual Studio .NET projects.)

<%@ Application Inherits="ProAspNet.Global" %>

We'll learn more about the syntax of global.asax in the next section, "Syntax of global.asax." With a precompiled global application file, you certainly don't risk exposing your source code over the Web to malicious attacks. However, even if you leave it as source code, you're somewhat safe.

The global.asax file, in fact, is configured so that any direct URL request for it is automatically rejected by IIS. In this way, external users cannot download or view the code it contains. The trick that enables this behavior is the following line of code, excerpted from machine.config:

ASP.NET registers with IIS to handle .asax resouces, but then processes those direct requests through the HttpForbiddenHandler HTTP handler. As a result, when a browser requests a .asax resource, an error message is displayed on the page, as shown in Figure 13-3.

Figure 13-3: Direct access to forbidden resources, such as *.asax files, results in a server error.

Of course, you can duplicate that line in your machine.config file, or even in the application's web.config file, and block direct access to other types of resources specific to your application. For this trick to work, though, make sure that the resource type is redirected to ASP.NET at the IIS level. In other words, you must register aspnet_isapi.dll to handle those files in the IIS metabase.

Syntax of global asax

Four elements determine the syntax of the global.asax file. They are: application directives, code declaration blocks, server-side tags, and server-side includes. These elements can be used in any order and number to compose a global.asax file.

Application Directives

The global.asax file supports three directives, two of which have been discussed in Chapter 1. The supported directives are: @Application, @Import, and @Assembly. The @Import and @Assembly directives work as we have seen in Chapter 1. The @Import directive imports a namespace into an application; the @Assembly directives links an assembly to the application at compile time.

The @Application directive supports a couple of attributes—Description and Inherits. Description can contain any text you want to use to describe the behavior of the application. This text has only a documentation purpose and is blissfully ignored by the ASP.NET parser. The Inherits attribute indicates a code-behind class for the application to inherit. It can be the name of any class derived from the HttpApplication class. The assembly that contains the class must be located in the Bin subdirectory of the application.

Just like the @Page directive, @Application accepts the CodeBehind attribute to allow for Visual Studio .NET editing. The attribute CodeBehind is ignored at run time.

Code Declaration Blocks

A global.asax file can contain code wrapped by a

If the language attribute is not specified, ASP.NET defaults to the language set in the configuration, which is Visual Basic .NET. As of version 1.1 of the .NET Framework, Visual Basic .NET, C#, JScript .NET, and J# are the only languages supported. (J# is supported only in version 1.1.)

The source code can also be loaded from an external file, whose virtual path is set in the Src attribute. The location of the file is resolved using Server.MapPath.

The Counter property defined in the global.asax in the preceding code works like an item stored in Application. Consider that concurrent access to Counter is not serialized; on the other hand, you have a strong typed, direct global item whose access is much faster than retrieving the same piece of information from a generic collection such as Application.

To access the property from a page, you must use the ASP.global_asax qualifier, shown here:

Response.Write(ASP.global_asax.Counter.ToString());

If you don't particularly like the ASP.global_asax prefix, you can alias it as long as you use C#. Add the following code to a C#-based page (or code-behind class) for which you need to access the globals:

using Globals = ASP.global_asax;

The preceding statement creates an alias for the ASP.global_asax class (or whatever name your global.asax class has). The alias—Globals in this sample code—can be used throughout your code wherever ASP.global_asax is accepted.

Response.Write(Globals.Counter.ToString());

Tracking Errors and Anomalies

When an error occurs, displaying a friendly page to the user is only half the job a good programmer should do. The second half of the work consists in sending appropriate notifications to the system administrator—if possible, in real time. A great help is the Error event of the HttpApplication object. Write an Application_Error event handler in your global.asax file and the system will call it back whenever an unhandled error occurs in the application—either in the user code, a component's code, or ASP.NET code.

In the Application_Error event handler, you first obtain specific information about the error and then implement the tracking policy that best suits your needs—for example, e-mailing the administrator, writing to the Windows Event Log, or dumping errors to a text file. The Server.GetLastError method returns an Exception object that just represents the unhandled exception you want to track down. URL information is contained in the Request object and even session or application state is available.

The following code demonstrates how to write an Application_Error event handler in global.asax to report run-time anomalies to the Event Log. An example of this code in action is shown in Figure 13-4.

Figure 13-4: The Event Viewer tracks an error on an ASP.NET application.

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

Your code doesn't necessarily have to create the event source. If the source specified in the Source property does not exist, it will be created before writing to the event log. The WriteEntry method takes care of that. Windows provides three log files: Application, Security, and System, which is reserved for device drivers. The Log property of the EventLog class gets and sets the log file to use. It is Application by default.

The HttpContext Class

During the various steps of the request's chain of execution, an object gets passed along from class to class—this object is the HttpContext object. HttpContext encapsulates all the information available about an individual HTTP request that ASP.NET is going to handle. Defined in the System.Web namespace, the HttpContext class is instantiated by the HttpRuntime object while the request-processing mechanism is being set up. Next, the object is flowed throughout the various stages of the request's lifetime, as Figure 13-5 demonstrates.

Figure 13-5: The HttpContext object, which encapsulates all the request information and gets flowed through the HTTP pipeline until the client response is generated.

Static Members

The programming interface of the HttpContext class includes two static members, one static property and one static method, to carry out general, noninstance-specific tasks. In the .NET Framework, a static member (a shared member in Visual Basic .NET jargon) of a class is a property or method that belongs to the type rather than to an instance of the type. All instances of the type share that same piece of code. To call static members, you must use the type name as the qualifier.

The HttpContext class has a static property named Current that returns the HttpContext object for the request being processed.

HttpContext cxt = HttpContext.Current;

In the HttpContext programming interface, you also find a static method. It is named GetAppConfig and returns configuration information for the specified section name. The information returned is read at the application level, which means it is a mix of machine.config and the application's main web.config file. The method returns an object whose actual type is determined by the characteristics of the section read.

Properties of the HttpContext Class

Table 13-7 enumerates all the properties exposed by the HttpContext class. The class represents a single entry point for a number of intrinsic objects such as ASP's Server, Request, and Response and new ASP.NET-specific Cache and User objects.

The Items property is a dictionary object—a hash table, to be exact—that can be used to share information between the modules and handlers involved with the particular request. By using this property, you can add your own information to the HttpContext object serving the request.

Methods of the HttpContext Class

Table 13-8 lists the methods specific to the HttpContext class. The table doesn't include methods inherited from the base Object class, such as ToString, GetType, and Equals.

In the all-encompassing container represented by the HttpContext object, a few popular objects also find their place. Among them are Server, Request, and Response. They are old acquaintances for ASP developers and indeed feature-rich elements of the ASP.NET programming toolkit. In ASP, the role of these objects was central, as they represented a large part of the ASP object model. The overall design of ASP.NET assigns to them a lower-level infrastructure role, but the set of properties and methods still makes these objects a fundamental resource for developers. Let's learn more about starting with the Server object.

The Server Object

The functionality of the ASP intrinsic Server object in ASP.NET is implemented by the HttpServerUtility class. An instance of the type is created when ASP.NET begins to process the request and is then stored as part of the request context. The bunch of helper methods that HttpServerUtility provides are publicly exposed to modules and handlers—including global.asax, pages, and Web services—through the Server property of the HttpContext object. In addition, to maintain ASP.NET coding as close as possible to the ASP programming style, several other commonly used ASP.NET objects also expose their own Server property. For example, both Page and HttpApplication show off a (technically speaking) redundant Server property. In this way, developers can use in the code, say, Server.MapPath without incurring compile errors. More important, they code exactly as they would have in ASP.

Intrinsic Objects? No, Intrinsic Properties

You should note that in ASP.NET, Server, Request, Response, and the like are in truth more intrinsic properties than intrinsic objects. In ASP, they were instances of COM components published to the ActiveX Scripting engine with easy-to-remember names such as Server, Request, and Response. To make them visible throughout all levels of code blocks, the objects were marked as globals, thereby gaining the label of intrinsically available objects.

The architecture is radically different in ASP.NET, in which the specific functionalities have been maintained and even enhanced but are integrated in the context of a true component-based model. The visibility of an object in a certain scope depends on strict syntax rules. Wide-range visibility, such as that of intrinsic objects in ASP, can be obtained only by replicating the objects in all scopes in which they are needed. Hence, the concept of intrinsic properties. Figure 13-6 compares the ASP and ASP.NET models.

Figure 13-6: In ASP, intrinsic objects are published as globals in the ActiveX Scripting engine in which all code blocks are processed. In ASP.NET, the visibility of an object is determined by the syntax.

The ASP.NET HttpServerUtility class extends and enhances the set of properties and methods defined on the COM object working as the ASP Server intrinsic object. Let's look at the new programming interface in more detail.

Properties of the HttpServerUtility Class

This class provides two properties, named MachineName and ScriptTimeout. The MachineName property returns the machine name and raises an HttpException if the name of the Web server machine is not readable. The ScriptTimeout property gets and sets the time in seconds that a request is allowed to be processed. This property accepts integers and is populated with the value of the executionTimeout attribute in the section of the machine.config file. The default value is 90 seconds; however, it is set to a virtually infinite value if the page runs with the attribute debug=true.

this.Server.ScriptTimeout = 30000000;

The ScriptTimeout property is explicitly and automatically set in the constructor of the class that represents the page. (See Chapter 2.)

Methods of the HttpServerUtility Class

Table 13-9 lists all methods exposed by the HttpServerUtility class. As you can see, they constitute a group of helper methods that come in handy at various stages of page execution. The class provides a couple of methods to create instances of COM components and a few others to deal with errors. Another group of methods relates to the decoding and encoding of content and URL.

HTML and URL encoding are ways of encoding characters to ensure that the transmitted text is not misunderstood by the receiving browser. HTML encoding, in particular, replaces <, >, &, and quotes with equivalent HTML entities such as <, >, &, and &quot;. It also encodes blanks, punctuation characters, and in general, all characters not allowed in an HTML stream. On the other hand, URL encoding is aimed at fixing the text transmitted in URL strings. In URL encoding, the same critical characters are replaced with different character entities than in HTML encoding.

Both HTML and URL encoding and decoding methods can return a string as well as output to any sort of TextWriter object—typically a StringWriter object. We'll talk about text writers in Chapter 16.

Embedding Another Page's Results

The Execute method allows you to consider an external page as a subroutine. When the execution flow reaches the Server.Execute call, control is passed to the specified page. The execution of the current page is suspended, and the external page is spawned. The response text generated by the child execution is captured and processed according to the particular overload of Execute that has been used.

public void Execute(string); public void Execute(string, TextWriter);

If the first overload is used, the response text is automatically embedded in the response of the main page. (See Figure 13-7.) If a TextWriter object is specified, the response text of the child execution is accumulated into the writer object and left at the disposal of the main page.

Figure 13-7: The response text generated by Execute, which can be automatically embedded in the main response or cached in a writer object.

The source code for the main page in Figure 13-7 is as follows:

<%@ Page Language="C#" %>

Pro ASP.NET (Ch13)

It's interesting to look at the internal implementation of the Execute method. Both the main and child pages are run by the same HttpApplication object as if they were the same request. What happens within the folds of Execute is a sort of context switch. First, the method obtains an HTTP handler from the application factory to serve the new request. The original handler of the main request is cached and replaced with the new handler. The spawned page inherits the context of the parent; when finished, any modification made to Session or Application is immediately visible to the main page.

The handler switching makes the whole operation extremely fast, as there's no need to create a new object to serve the request. When the child page returns, the original handler is restored. The execution of the main page continues from the point in which it was stopped but using the context inherited from the child page.

Server-Side Redirection

The Transfer method differs from the Execute method in that it terminates the current page after executing the specified page. The new page runs as if it was the originally requested one. The Transfer method has the following two overloads:

public void Transfer(string); public void Transfer(string, bool);

The first overload simply redirects to the specified page. The second overload clears or preserves the QueryString and Form collections based on the value of the Boolean argument. When you call the first overload, the collections are always cleared unless the IsPostBack property on the original page is set to true.

The Execute and Transfer methods have a similar architecture. Both methods use the same internal procedure to perform the handler switch. In both cases, the same HttpApplication object is used to carry out the new request, as shown in Figure 13-8.

Figure 13-8: Comparing the internal architecture of the Execute and Transfer methods.

Note that when you call Transfer, the new page request is served immediately. However, the previous request is terminated only when the internal call to Execute, used to implement the redirect, has returned. The following pseudocode illustrates the behavior of the method:

public void Transfer(string path, bool preserveForm) { // the null argument indicates that no writer should // be used in the call to Execute ExecuteInternal(path, null, preserveForm); Context.Response.End(); }

All the code that might be following the call to Transfer in the main page is never executed. In the end, Transfer is just a page redirect method. However, it is particularly efficient for two reasons. First, no roundtrip to the client is requested as is the case, for example, with Response.Redirect. Second, the same HttpApplication that was serving the caller request is reused, thus limiting the impact on the ASP.NET infrastructure.

Late-Bound COM Objects

The HttpServerUtility class provides you with the ability to create late-bound COM objects in much the same way you do in ASP. The methods are CreateObject and CreateObjectFromClsid. They are marked to return a generic Object type. However, the actual type they return is System.__ComObject. Objects can be created either from the string representation of the class CLSID or from the progID. The following code creates an instance of a COM component using the CLSID:

Dim strClsid As String = "42754580-16b7-11ce-80eb-00aa003d7352" Dim comObj As Object = Server.CreateObject(strClsid)

When assigned to a variable declared of type Object, an object is said to be late bound—as opposed to early-bound, strongly typed objects. Late-bound objects can hold references to any object, but they lack many advantages of early-bound objects. Early-bound objects should be used whenever possible because they are significantly faster than late-bound objects and make your code easier to develop, read, and maintain.

Primarily for backward-compatibility reasons, you might sometimes create late-bound instances of COM objects. Using COM objects in ASP.NET applications is a common necessity in real-world projects. The best way to import COM functionality in .NET applications entails the use of managed wrappers—special classes that expose the type library of the COM class as a .NET class. Managed wrappers are usually created by Visual Studio .NET when you reference a COM object in your project.

Although not especially effective as an approach, the Server.CreateObject method can be used to create a late-bound instance of a COM component. The ideal language for late binding is Visual Basic .NET; however, bear in mind that late binding is supported as long as the Strict option is Off (the default).

The following code shows how to fill an ADO Recordset object using the ASP programming style:

<%@ Page Language="VB" AspCompat="true" %>

Note the use of the AspCompat attribute in the @Page directive. Apartment-threaded COM components can be created only in ASP.NET pages that have the AspCompat attribute set to true. Before an attempt to create the object is made, the CreateObject method checks the threading model of the component. If the page is already working in ASP compatibility mode—that is, the AspCompat attribute is true—the object is created, regardless of the threading model of the component. If the AspCompat attribute is set to false (the default), CreateObject reads the threading model of the COM component from the registry. If the threading model is apartment, or no threading model is specified, an exception is thrown; otherwise, the object is successfully created. The following pseudocode shows the internals of the HttpServerUtility'sCreateObject method:

public object CreateObject(string progID) { Type managedType = Type.GetTypeFromProgID(progID); if (!IsAspCompatMode) { string threadingModel = GetThreadingModel(managedType.GUID); if (threadingModel == "apartment") throw new HttpException("..."); } return Activator.CreateInstance(managedType); }

Note also that the use of the AspCompat attribute is not strictly necessary with the ADO library because the ADO library supports both the apartment and free-threading model.

The Importance of AspCompat

Running STA components in a multithreaded apartment environment (MTA) such as ASP.NET is strongly discouraged performance-wise. The AspCompat attribute is designed to avoid this critical situation. Let's see how and why.

To process HTTP requests, normally ASP.NET uses a pool of threads from an MTA. Objects in an MTA execute on any thread and allow any number of methods to occur simultaneously. Single-threaded apartment COM components (for example, all Visual Basic 6 COM components) execute on the particular thread in which they were created and allow only one method to execute at a time. Until special countermeasures are taken, when you run an STA component in an MTA environment continued thread switching is likely to happen. More importantly, a thread switch can happen only when the particular thread in the pool that can serve the STA component is available. As you can see, this situation is heralding poor performance issues if not even deadlock.

By setting the AspCompat attribute to true, you force ASP.NET to use an STA thread pool to accommodate the COM object on a per-page basis. In this case, both the caller thread and the callee component live in the same apartment and no extra overhead is involved. As a matter of fact, ASP.NET pages that contain STA COM components run better in STA mode than in an, otherwise generally faster, MTA mode.

Because the AspCompat attribute is processed after the instance of the page class is created, you should also avoid creating instances of STA COM objects in the page constructor. If you don't avoid doing this, the page will be served by an MTA thread regardless of the value of AspCompat and probably incur poor performance.

Setting AspCompat to true also has another advantage—it makes ASP intrinsic objects (ObjectContext, Request, Response, and so forth) available to the COM component. ASP.NET creates unmanaged ASP intrinsic objects and passes them to the COM components used in the page.

The Response Object

In ASP.NET, the functionality of the ASP intrinsic Response object is provided through the HttpResponse class. An instance of the HttpResponse object is created when the HTTP pipeline is set up to serve the request. The instance is then linked to the HttpContext object associated with the request. The HttpResponse class defines methods and properties to manipulate the text that will be sent to the browser. Although user-defined ASP.NET code never needs to use the HttpResponse constructor, looking at it is still useful to get the gist of the class:

public HttpResponse(TextWriter writer);

As you can see, the constructor takes a writer object, which will then be used to accumulate the response text that controls the generated page. The actual writer used by HttpResponse is the HttpWriter class. All calls made to Response.Write are resolved in terms of internal calls to the HttpWriter object.

Properties of the HttpResponse Class

All properties of the class are grouped and described in Table 13-10. You set a few of these properties to configure key fields on the HTTP response packet, such as content type, character set, page expiration, and status code.

As you can see, a few of the HttpResponse properties are provided only for backward compatibility with previous versions of ASP. In some cases (for example, BufferOutput and StatusDescription), the property has just been renamed; in other cases, the properties deprecated have been replaced by a more general and powerful API. This is certainly the case for cache and expiration properties.

Setting the Response Cache Policy

In ASP, the Response object has three properties dedicated to control the ability of the page being sent to the browser to be cached. The Expires and ExpiresAbsolute properties define relative and absolute times at which the page cached on the client expires and is no longer utilized by the browser to serve a user request. In fact, if the user navigates to a currently cached page, the cached version is displayed and no roundtrip occurs to the server.

A third property somehow related to page caching is CacheControl. The property sets a particular HTTP header—the Cache-Control header. The Cache-Control header controls how a document is to be cached across the network. Allowable values come from the HttpCacheability enumeration and are listed in Table 13-11.

The HttpCacheability enumeration has a few more members like Server. This member has nothing to do with HTTP caching and, in fact, sets the Cache-Control header to no-cache. However, it indicates that the page is cached on the origin server.

In ASP.NET, all caching capabilities are grouped in the HttpCachePolicy class. With regard to page caching, the class has a double role. It provides methods for both setting cache-specific HTTP headers and controlling the ASP.NET page output cache. In this chapter, we're mostly interested in the HTTP headers, and we'll keep page output caching warm for Chapter 14.)

To set the visibility of a page in a client cache, use the SetCacheability method of the HttpCachePolicy class with one of the values in Table 13-11. To set an expiration time, use the SetExpires method, which takes for input an absolute DateTime object. Finally, to set a lifetime for the cached page, pass to SetExpires the current time plus the desired interval.

Setting an Output Filter

In ASP.NET, a new component makes its debut—the response filter. A response filter is a Stream-derived object that can be associated with the HttpResponse object to monitor and filter any output being generated. If you set the Filter property with the instance of an object derived from Stream, all output being written to the underlying HTTP writer first passes through your output filter.

The custom filter, if any, is invoked during the HttpResponse's Flush method before the actual text is flushed and then sent to the client. Building a response filter is a matter of creating a new class and making it inherit from Stream and override some of the methods. The class should have a constructor that accepts a Stream object. In light of this, a response filter class is more a wrapper stream class than a purely inherited stream class. If you try to set Response.Filter with a new instance of, say, MemoryStream or FileStream, an exception is thrown.

The following listing shows how to create a stream class that works as a response filter. For simplicity, the class inherits from MemoryStream. You might want to make it inherit from Stream, but in this case you need to override (because they are abstract) a number of methods, such as CanRead, CanWrite, CanSeek, and Read. The class converts lowercase characters to uppercase.

public class MyFilterStream : MemoryStream { private Stream m_Stream; public MyFilterStream(Stream filterStream) { m_Stream = filterStream; } // The Write method actually does the filtering public override void Write(byte[] buffer, int offset, int count) { byte[] data = new byte[count]; Buffer.BlockCopy(buffer, offset, data, 0, count); // Change lowercase chars to uppercase. for (int i = 0; i < count; i++) { if (data[i] >= 'a' && data[i] <= 'z') data[i] -= ('a'-'A'); } m_Stream.Write(data, 0, count); } }

Use the following code to associate this output filter with the Response.Filter property. Here's a sample page:

Methods of the HttpResponse Class

Table 13-12 lists all the methods defined on the HttpResponse class. The class contains one deprecated method added only for compatibility with previous versions of ASP. This method is AddHeader.

The Redirect method causes the specified page to execute. However, the trick used in this case is less efficient than with Server.Execute or Server.Transfer. The method sends a response that the browser interprets as an invitation to request the specified page. Although the final effect is always that of redirecting the user to a different page, the way in which this effect is obtained requires a roundtrip. The HttpResponse's Redirect method has two overloads:

public void Redirect(string); public void Redirect(string, bool);

The second overload lets you specify whether the execution of the current page should terminate. By default, the redirection is unconditional and the execution of the current page is stopped.

The Request Object

The HttpRequest object groups all the information contained in the HTTP packet that represents the incoming Web request. The contents of the various HTTP headers, the query string, or the form's input fields, path, and URL information are organized in a series of collections and other ad hoc objects for easy and effective programmatic access. The HttpRequest object is populated as soon as ASP.NET begins working on a Web request and is made available through the Request property of HttpContext.

HttpRequest exposes a fair number of properties and is one of the objects that has been more significantly enriched in the transition from ASP to ASP.NET.

Properties of the HttpRequest Class

The class properties can be classified in three groups based on the type of information they contain: type of the request, client data, and connection. Table 13-13 lists the properties that define the type of request being issued.

Initially, CurrentExecutionFilePath and FilePath share the same content—the requested URL. However, in cases of server-side redirects, the value of CurrentExecutionFilePath is automatically updated. You should check CurrentExecutionFilePath for up-to-date information about the target URL.

The HttpBrowserCapabilities object groups in a single place values that identify a fair number of browser capabilities, including support for ActiveX controls, scripting languages, frames, cookies, and more. (Browser capabilities was discussed in Chapter 4.) When the request arrives, the user agent information is used to identify the requesting browser and a new empty instance of the HttpBrowserCapabilities class is created. The instance is then populated with browser-specific information read from the machine.config file. The information returned through HttpBrowserCapabilities is in no way dynamically set by the browser. The browser sets only the user agent string, and ASP.NET uses that small piece of information as a key to retrieve statically set information from the configuration.

The HttpRequest's Browser property also supports mobile scenarios in version 1.1 of the .NET Framework. In this case, the actual object returned is of class MobileCapabilities—a HttpBrowserCapabilities-derived class. When you obtain the Browser property reference you should cast it as a MobileCapabilities class.

Table 13-14 lists the HttpRequest properties that expose the client data that ASP.NET pages might want to use for server-side processing. The following table includes, for example, cookies, forms, and query string collections.

The Params collection combines four different but homogeneous collections—QueryString, Form, ServerVariables, and Cookies—and replicates the information contained in each of them. Although not particularly high, the risk of creating conflicting names does exist especially because the entries in Form, QueryString, and Cookies are decided by the programmers. The collections are added in the following order: QueryString, Form, Cookies, and finally ServerVariables.

Table 13-15 lists the properties that relate to the open connection.

The Uri class provides an object representation of a Uniform Resource Identifier (URI)—a unique name for a resource available on the Internet. The Uri class provides easy access to the parts of the URI as well as properties and methods for checking host, loopback, ports, and DNS.

The server variables set in the ServerVariables collection are decided by the run-time environment that processes the request. The information packed in the collection is for the most part excerpted from the HTTP worker request object; another part contains Web server–specific information. The ServerVariables collection is just a friendly name/value model to expose that information.

In ASP.NET applications, the usefulness of ServerVariables is limited, as a large number of variables are also exposed as individual properties. For example, the URL and path information—whose corresponding variables are URL and PATH_INFO—are also available through more direct properties on the HttpRequest object, such as Url and PathInfo. (See Table 13-15.) However, some information is not available to Web applications other than through server variables. A few examples are the name of the Web server software (SERVER_SOFTWARE) and the meta path of the current instance of the application in IIS (INSTANCE_META_PATH).

Methods of the HttpRequest Class

Table 13-16 lists all methods exposed by the HttpRequest class. The list doesn't include methods such as Equals and ToString, which are inherited from Object.

The SaveAs method lets you create a file to store the entire content of the HTTP request. Note that the storage medium can only be disk file; no stream or writer can be used. Since ASP.NET by default isn't granted write permissions, this method causes an access denied exception unless you take ad hoc measures. Granting the ASPNET account full control over the file to create (or over the whole folder) is one of the possible ways to successfully use the SaveAs method. The following listing shows possible content that SaveAs writes to disk.

GET /test/main.aspx HTTP/1.1 Connection: Keep-Alive Accept: */* Accept-Encoding: gzip, deflate Accept-Language: en-us Cookie: ASP.NET_SessionId=3ogcmn550gnzl4zlao5h3545 Host: expo-star User-Agent: Mozilla/ 4.0 (compatible; MSIE 6.0; Windows NT 5.0; COM+ 1.0.2204; .NET CLR 1.1.4322)

Conclusion

In this chapter, we covered some basic objects that are the foundation of ASP.NET programming—Server, Response, Request, and others. An ASP.NET application is represented by an instance of the HttpApplication class properly configured by the contents of the global.asax file. And both the HttpApplication class and the global.asax files found their space in this chapter, too.

In ASP.NET, as well as in ASP, you can use an unqualified Server object in the source of the page. The context that allows you to execute that code is different in the two models, though. In ASP, Server is the name that identifies an instance of a COM component globally available in the scripting environment. In ASP.NET, Server is simply a property exposed by the page class. We summarized this key architectural difference with the expression intrinsic properties to distinguish it from the intrinsic objects of ASP.

While discussing the interface of the objects that generate the context of an HTTP request, we reviewed in detail some specific programming issues such as the instantiation of late-bound COM objects, server-side page redirection, and the setup of response filters. In the next chapter, we'll discuss an important topic related to Web applications and ASP.NET—state management. Fundamentally, Web applications are stateless, but ASP.NET provides various mechanisms for maintaining application state and caching pages.

Resources

• A Matter of Context (http://msdn.microsoft.com/library/en-us/dnaspnet/html/asp01242002.asp)
• ASP.NET Internals Chat (http://msdn.microsoft.com/chats/vstudio/vstudio_061302.asp)
• HTTP Modules (http://msdn.microsoft.com/msdnmag/issues/02/05/asp/asp0205.asp)
• Setting Up Global Objects with the global.asax File (http://www.csharphelp.com/archives/archive206.html)
• Happy Hunting Extend the ASP.NET page output cache and get inside AspCompat (http://www.aspnetpro.com/features/2003/03/asp200303jp_f/asp200303jp_f.asp)

Chapter 14 ASP NET State Management