HttpModules

At this point, we have a working comment tracking control, but its usefulness is limited in any real-world development. Adding the control to all the ASP.NET pages in a large application can take a lot of time. You would also need to remove the pages before making your application go live, which could potentially add errors to previously tested code. What we need is a way to add the control to every page automatically. This is where HttpModules come in.

An HttpModule is a class that, for every page, allows you to handle events that are fired at various stages of the creation of the page. The .NET framework uses HttpModules for authenticating users and managing the session state. The rest of this chapter will show you how to write an HttpModule to manipulate the output of any arbitrary aspx file.

IHttpModule Interface

To write an HttpModule, you need to write a class that implements the IHttpModule interface. The IHttpModule interface is quite simple with only two methods: Dispose() and Init(). For most modules, only the Init() method is of interest, but if you allocate any unmanaged resources that are of module scope, you should free them in the Dispose() method.

The Init() method is where you normally attach an event handler to any events that you wish to handle.

You should be careful about allocating resources in the Init() method because anything allocated and assigned to a class variable will have application scope. This is because HttpModules are created when the application is initialized and destroyed after the application has completed.

Events

There are a number of events that you can handle with an HttpModule. Table 15.16 describes the different events.

Table 15.16. Events Handled by HttpModules

Event	Description
AcquireRequestState	Called before the intrinsic Request object is set up.
AuthenticateRequest	Called to allow authentication of a request.
AuthorizeRequest	Called to allow authorization of a request.
BeginRequest	Called at the beginning of the request before any other processing has been done.
Disposed	Called during the Application object's disposal process, when the application is shutting down.
EndRequest	Called after all processing of the request has been done.
Error	Called if there was an unhandled error during the processing of the request.
PostRequestHandlerExecute	Called after the request handler has finished executing. The request handler is usually a class derived from the System.Web.UI.Page class.
PreRequestHandlerExecute	Called after all pre-request processing (including setting up the intrinsic Request object) has been completed, but before the request handler is called.
PreSendRequestContent	Called before the body of the response is sent.
PreSendRequestHeaders	Called before the response headers are sent.
ReleaseRequestState	Called after the intrinsic Request object's data is released.
ResolveRequestCache	Called after the request cache is resolved.
UpdateRequestCache	Called after the request cache is updated.

If you need to terminate the processing of a page after handling an event, you should call the CompleteRequest() method of the HttpApplication class. If the CompleteRequest() method is not called, then normal processing will continue after your event completes.

Basic HttpModule

Lets now take a look at a simple HttpModule. A complete module will do two things. First, it will implement the IHttpModule interface. Second, it will handle one or more of the events listed in Table 15.16. If it did not handle any of the events, it would never be able to do anything useful. Listing 15.7 shows a basic HttpModule.

Listing 15.7 C# Code for a Minimum Implementation HttpModule

 public class MyHttpModule : IHttpModule {     // Constructor     public MyHttpModule()     {     }     // Implement IHttpModule Methods     public void Init(HttpApplication context)     {         context.Error += new EventHandler(OnError);     }     public void Dispose()     {     }     // Implement the event handler.     public void OnBeginError(Object sender, EventArgs e)     {         HttpApplication app=sender as HttpApplication;         // Do something here     } } 

Configuration

After an HttpModule has been written, it needs to be registered so that it can be loaded when the Web application starts. To do so, add an entry inside the <HttpModules> section of either the web.config file or the machine.config file. Adding the entry to the web.config file causes the module to load when a specific Web application starts. Adding the entry to the machine.config file causes the module to load when any Web application starts.

The format of entries in the <HttpModules> section is as follows:

 <configuration>    <system.web>         <httpModules />     </system.web> </configuration> 

An <add> entry adds a new HttpModule; a <remove> entry will remove an inherited HttpModule (possibly from a higher level web.config or from machine.config); and a <clear> entry will remove all HttpModules. You will need an <add> entry before your module can be used. If you added a module in the machine.config file, you can remove it in the web.config file of a specific Web application using a <remove> entry in the Web application's web.config file. This allows you to load an HttpModule for every Web application except ones that have a <remove> entry in the web.config file.