Writing an HttpModule

Writing an HttpModule is fairly straightforward, though complex issues can arise, depending on what you are trying to do. To write an HttpModule, you must do the following:

1. Write a class that implements the IHttpModule interface. The IHttpModule interface has two methods : an Init method and a Dispose method.

2. Implement a method in the class you wrote to handle the event you wish to capture.

3. Add an entry in the Init method of your class to capture the event you wish to handle.

4. Add an entry inside the <HttpModules> section of either your web.config or machine.config file to register your HttpModule. The entry should be in the web.config file to register the module for a single application. The entry should be in the machine.config file to register the module for all applications.

Your module can do either simple or complex things, but it is important to remember that you are handling events that occur for every .aspx file request. If your event-handling method takes a long time to complete, you will affect the performance of your server noticeably.

Module Lifetime

Before you get into the details of writing an HttpModule, it is important that you understand the lifetime of your module.

HttpModules are all constructed when an application is first started. The application maintains a reference to the module. This reference is released when the application is shut down. So, your HttpModule has approximately the same lifetime that your application does. This is important to know because you need to be sure that your HttpModule doesn't store things in class scope unless absolutely necessary, because the stored items won't go out of scope until the application ends. Most resources should be allocated when the event handler starts and released when the event handler ends.

Implementing the IHttpModule Interface

The IHttpModule interface is a simple interface with only two methods. Here is the interface description:

 public interface IHttpModule  {      void Init(HttpApplication context);      void Dispose();  } 

C# uses inheritance to tell the compiler that you are going to implement an interface. Even though C# allows only single inheritance for classes, you can inherit multiple interfaces. Class inheritance can be combined with interface inheritance. Here is an implementation of the interface in C#:

 public class MyHttpModule : IHttpModule  {      // Constructor      public MyHttpModule()      {      }      // Implement IHttpModule Methods      public void Init(HttpApplication context)      {      }      public void Dispose()      {      }  } 

The interface inheritance mechanism is a little different with Visual Basic .NET than it is in C#. Visual Basic .NET uses the Implements keyword to signify that an interface is implemented in the class and also that a method implements a given method in the interface. Here is the implementation in Visual Basic .NET:

 Public Class MyHttpModule    Implements IHttpModule    Public Sub Init(ByVal context As HttpApplication) Implements IHttpModule.Init    End Sub    Public Sub Dispose() Implements IHttpModule.Dispose    End Sub  End Class 

As you can see, implementing an interface in either C# or Visual Basic .NET is simple and straightforward. One difference between them is that, because Visual Basic .NET uses the Implements keyword to indicate which class method implements which interface method, it is not necessary for the class method to have the same name as the interface method. In C#, the class method and interface method must have the same name .

Handling Events

Two tasks are involved in handling an event. First, you need to implement a method to handle the event, and then you need to register the method with the event.

Implementing a method to handle an event is just like implementing any other method, except that it must match the signature of the event. All events that the HttpApplication class exposes should be handled with a method as follows :

 //C#  public void OnEventName(Object sender, EventArgs e)  {      // Do something here  }  'VB  Public Sub OnEventName(ByVal sender AS Object,ByVal e AS EventArgs)      ' Do something here  End Sub 

The source object is usually used as an object of type System.Web.HttpApplication . Although the event handler method can be named anything you like, the convention is to name it On EventName , where EventName is the name of the event you are handling.

Registering the method with the event is normally done in the Init method. To do this, add the following line to the Init method:

 //C#  context.EventName += new EventHandler(OnEventName);  'VB  AddHandler context.EventName, AddressOf OnEventName 

Any number of modules can hook into an event this way. If you accidentally hook into the same event twice, your method will be called twice for every event.

You've now learned the basics for handling an event that the HttpApplication object generates. Listing 25.1 is a complete HttpModule, implemented in C#, that hooks into the BeginRequest event but doesn't actually do anything. Listing 25.2 is the same HttpModule implemented in Visual Basic.NET.

Listing 25.1 C# Code for a Minimum Implementation HttpModule

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

Listing 25.2 Visual Basic .Net Code for a Minimum Implementation HttpModule

 Public Class MyHttpModule    Public Sub Init(ByVal context As HttpApplication) Implements IHttpModule.Init        AddHandler context.BeginRequest, AddressOf OnBeginRequest    End Sub    Public Sub Dispose() Implements IHttpModule.Dispose    End Sub    ' Implement the event handlers     Public Sub OnBeginRequest(ByVal sender As Object, ByVal e As EventArgs)        ' Do something here    End Sub  End Class 

You can use these minimum implementation HttpModules as a starting point when you develop your own modules.

HttpModule Configuration

After an HttpModule has been written, it must 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:

 <httpModules>     <add type="classname,assemblyname" name="modulename" />     <remove type="classname,assemblyname" name="modulename" />     <clear />  </httpModules> 

An <add> entry adds a new HttpModule; a <remove> entry removes an inherited HttpModule; a <clear> entry removes all HttpModules. You 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.