Note

HTTP modules differ from HTTP handlers. An HTTP handler returns a response to a request that is identified by a file name extension or family of file name extensions. In contrast, an HTTP module is invoked for all requests and responses. It subscribes to event notifications in the request pipeline and lets you run code in registered event handlers. The tasks that a module is used for are general to an application and to all requests for resources in the application.

How HTTP Modules Work

Modules must be registered to receive notifications from the request pipeline. The most common way to register an HTTP module is in the application‘s Web.config file. In IIS 7.0, the unified request pipeline also enables you to register a module in other ways, which includes through IIS Manager and through the Appcmd.exe command-line tool. For more information, see Configuring Handler Mappings in IIS 7.0 and Start Appcmd.exe.

When ASP.NET creates an instance of the HttpApplication class that represents your application, instances of any modules that have been registered are created. When a module is created, its Init method is called and the module initializes itself. For more information, see ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0 and ASP.NET ASP.NET Application Life Cycle Overview for IIS 7.0.

In a module‘s Init method, you can subscribe to various application events such as BeginRequest or EndRequest by binding the events to methods in the module.

When application events are raised, the appropriate method in your module is called. The method can perform whatever logic is required, such as checking authentication or logging request information. During event handling, the module has access to the Context property of the current request. This enables you to redirect the request to an alternative page, modify the request, or perform any other request manipulation. For example, if the module checks authentication, the module might redirect to a login or error page if the credentials are not correct. Otherwise, when the module‘s event handler has finished running, ASP.NET calls the next process in the pipeline. This might be another module or might be the appropriate HTTP handler (such as an .aspx file) for the request.

HTTP Modules versus Global.asax Files

You can implement much of the functionality of a module in the application‘s Global.asax file, which enables you to respond to application events. However, modules have an advantage over the Global.asax file because they are encapsulated and can be created one time and used in many different applications. By adding them to the global assembly cache and registering them in the Machine.config file, you can reuse them across applications. For more information, see Global Assembly Cache.

The advantage of using the Global.asax file is that you can handle other registered events such as Session_Start and Session_End. In addition, the Global.asax file enables you to instantiate global objects that are available throughout the application.

You should use a module whenever you must create code that depends on application events, and when the following conditions are true:

• You want to re-use the module in other applications.

• You want to avoid putting complex code in the Global.asax file.

• The module applies to all requests in the pipeline (IIS 7.0 Integrated mode only).

You should add code in the Global.asax file whenever you must create code that depends on application events and you do not have to reuse it across applications. You can also use the Global.asax file when you have to subscribe to events that are not available to modules, such as Session_Start.

Creating an HTTP Module

The general process for writing an HTTP module is as follows:

• Create a class that implements the IHttpModule interface.

• Write a handler for the Init method. The initialization method should initialize your module and subscribe to any application events you need. For example, if you want to append something to responses, you might subscribe to the EndRequest event. If you want to perform custom authentication logic, you might subscribe to the AuthenticateRequest event. For more information about application events, see ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0.

• Write code for the events that you have subscribed to.

• Optionally implement the Dispose method if the module requires cleanup.

• Register the module in the Web.config file. For more information, see Walkthrough: Creating and Registering a Custom HTTP Module

For information about how to move a module from an application that is running in IIS 6.0 or earlier versions to an application that runs on in IIS 7.0, see Moving an ASP.NET Application from IIS 6.0 to IIS 7.0.