Introduction to HTTP Modules

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

ASP.NET HTTP modules are similar to ISAPI filters in that they run for all requests. However, they are written in managed code and are fully integrated with the life cycle of an ASP.NET application.

Typical uses for HTTP modules include:

  • Security. Because you can examine incoming requests, your HTTP module can perform custom authentication or other security checks before the requested page, XML Web service, or handler is called.

  • Statistics and logging. Because HTTP modules are called on every request, you can gather request statistics and logging information in a centralized module, rather than in individual pages.

  • Custom headers or footers. Because you can modify the outbound response, you can inject content such as custom header information into every page or XML Web service response.

ASP.NET uses modules to implement various application features, including 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.

NoteNote

HTTP modules differ from HTTP handlers. HTTP modules are called for all requests and responses, whereas HTTP handlers run only in response to specific requests. For more information, see Introduction to HTTP Handlers.

How HTTP Modules Work

You register a custom HTTP modules in your application's Web.config file. 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.

In a module's Init method, you can subscribe to various application events such as BeginRequest or EndRequest by binding the events to methods you have created in the module. When these events are raised, the appropriate method in your module is called and the module can perform whatever logic is required, such as an authentication check 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 your module includes an authentication check, the module might check for credentials and redirect to a login or error page if the credentials were not correct. Otherwise, when the module's event handler has finished running, ASP.NET calls the next process in the pipeline, which 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 in that they are encapsulated and can be created once and used in many different applications. By adding them to the Global Assembly Cache (GAC) and registering them in the Machine.config file, you can reuse them across applications. For more information, see Global Assembly Cache.

However, the advantage to using the Global.asax file is that you can place code in other registered module events such as Session_Start and Session_End methods. 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 need to create code that depends on application events and you either wish to reuse the module in other applications or you don't want to place complex code in the Global.asax file. You should place code in the Global.asax file whenever you need to create code that depends on application events and you do not need to reuse it across applications, or when you need to subscribe to events such as Session_Start that are not available to modules.

Creating an HTTP Module

You can create a custom HTTP module by creating a class that implements the IHttpModule interface and then registering it in the Web.config file. The general process for writing an HTTP module is:

  • Create a class that implements the IHttpModule frlrfSystemWebIHttpModuleClassTopic interface.

  • Write a handler for the InitfrlrfSystemWebIHttpModuleClassInitTopic method. Your init method should initialize your module and subscribe to any application events you need. For example, you might subscribe to the EndRequest event if you want to append something to responses, or you might subscribe to the AuthenticateRequest event if you wish to perform custom authentication logic. For more information on application events, see ASP.NET Application Life Cycle Overview.

  • Write code for the events you have subscribed to.

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

  • Register the module in the Web.config file.

For more information, see How to: Create Custom HTTP Modules.

See Also

Tasks

How to: Create Custom HTTP Modules

Concepts

ASP.NET Application Life Cycle Overview