HTTP Handlers and HTTP Modules Overview

HTTP Modules

An HTTP module is an assembly that is called on every request that is made to your application. HTTP modules are called as part of the request pipeline and have access to life-cycle events throughout the request. HTTP modules therefore let you examine incoming requests and take action based on the request. They also let you examine the outgoing response and modify it.

In IIS 6.0, the ASP.NET request pipeline is separate from the Web server request pipeline. In IIS 7.0, the ASP.NET request pipeline and the Web server request pipeline can be integrated into a common request pipeline. In IIS 7.0, this is referred to as Integrated mode. The unified pipeline has several benefits for ASP.NET developers. For example, it lets managed-code modules receive pipeline notifications for all requests, even if the requests are not for ASP.NET resources. However, if you want, you can run IIS 7.0 in Classic mode, which emulates ASP.NET running in IIS 6.0. For more information, see ASP.NET Application Life Cycle Overview for IIS 7.0.

ASP.NET HTTP modules are like ISAPI filters because they are invoked for all requests. However, they are written in managed code and are fully integrated with the life cycle of an ASP.NET application. You can put custom module source code in the App_Code folder of your application, or you can put compiled custom modules as assemblies in the Bin folder of an application.

ASP.NET uses modules to implement various application features, which includes forms authentication, caching, session state, and client script services. In each case, when those services are enabled, the module is called as part of a request and performs tasks that are outside the scope of any single page request. Modules can consume application events and can raise events that can be handled in the Global.asax file. For more information about application events, see ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0 and ASP.NET Application Life Cycle Overview for IIS 7.0.

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.

Note

For modules that operate in the IIS 7.0 integrated pipeline, you should register event handlers in the Init method.

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.

Note

In IIS 7.0, the integrated pipeline enables managed modules to subscribe to pipeline notifications for all requests, not just requests for ASP.NET resources. Event handlers in the Global.asax file are invoked only for notifications during requests for resources in the application. Custom modules in Integrated mode can be explicitly scoped to receive event notifications only for requests to the application. Otherwise, custom modules receive event notification for all requests to the application. If the precondition attribute of the add element of the modules section is set to "managedHandler", the module is scoped to the application.

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.