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.
 Note |
|---|
| 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. |
Implement the Module
- Create a new Visual Studio .NET C# Class Library project named MyModule.
- Set a reference to the System.Web.dll assembly.
- Add the following directive to the class:
- Rename the class SyncModule.cs, and then change the class definition to reflect this.
- Implement the IHttpModule interface. Your class definition should appear as follows:
public class SyncModule : IHttpModule
- Decide to which events you will subscribe. The following list outlines the available events from the HttpApplication object to which you can subscribe:
- AcquireRequestState: Call this event to allow the module to acquire or create the state (for example, session) for the request.
- AuthenticateRequest: Call this event when a security module needs to authenticate the user before it processes the request.
- AuthorizeRequest: Call this event by a security module when the request needs to be authorized. Called after authentication.
- BeginRequest: Call this event to notify a module that new request is beginning.
- Disposed:
Call this event to notify the module that the application is ending for
some reason. Allows the module to perform internal cleanup.
- EndRequest: Call this event to notify the module that the request is ending.
- Error: Call this event to notify the module of an error that occurs during request processing.
- PostRequestHandlerExecute: Call this event to notify the module that the handler has finished processing the request.
- PreRequestHandlerExecute: Call this event to notify the module that the handler for the request is about to be called.
- PreSendRequestContent: Call this event to notify the module that content is about to be sent to the client.
- PreSendRequestHeaders: Call this event to notify the module that the HTTP headers are about to be sent to the client.
- ReleaseRequestState: Call this event to allow the module to release state because the handler has finished processing the request.
- ResolveRequestCache:
Call this event after authentication. Caching modules use this event to
determine if the request should be processed by its cache or if a
handler should process the request.
- UpdateRequestCache: Call this event after a response from the handler. Caching modules should update their cache with the response.
This sample uses the BeginRequest event.
- Implement the Init and Dispose methods of the IHttpModule interface as follows:
public void Init(HttpApplication app)
{
app.BeginRequest += new EventHandler(OnBeginRequest);
}
public void Dispose(){ }
- Create a delegate for an event as follows:
public delegate void MyEventHandler(Object s, EventArgs e);
- Define a private local variable of the type MyEventHandler to hold a reference to the event:
private MyEventHandler _eventHandler = null;
- Create an event that hooks up the delegate to the method in the Global.asax file or class that inherits from the HttpApplication object:
public event MyEventHandler MyEvent
{
add { _eventHandler += value; }
remove { _eventHandler -= value; }
}
- Create the OnBeginRequest method, which hooks up to the BeginRequest event of HttpApplication:
public void OnBeginRequest(Object s, EventArgs e)
{
HttpApplication app = s as HttpApplication;
app.Context.Response.Write("Hello from OnBeginRequest in custom module.<br>");
if(_eventHandler!=null)
_eventHandler(this, null);
}
- Compile the project.
Deploy the Module
- Create a new directory under C:\Inetpub\Wwwroot named Module.
- Create a subdirectory named Bin in the newly created Module directory. The resultant path is C:\Inetpub\Wwwroot\Module\Bin.
- Copy MyModule.dll from your project's Bin\Debug directory to the C:\Inetpub\Wwwroot\Module\Bin directory.
- Follow these steps to mark the new Module directory as a Web application:
- Open Internet Services Manager.
- Right-click the Module directory, and then click Properties.
- On the Directory tab, click Create.
- Click OK to close the Module Properties dialog box.
Configure the System
- In the C:\Inetpub\Wwwroot\Module\ directory, create a new file named Web.config.
- Paste the following text in Web.config:
<configuration>
<system.web>
<httpModules>
<add name="MyModule" type="MyModule.SyncModule, MyModule" />
</httpModules>
</system.web>
</configuration>
Test the Module
- In the C:\Inetpub\Wwwroot\Module directory, create a new .aspx file named Test.aspx.
- Paste the following text into Test.aspx:
<%@Page Language="C#"%>
<% Response.Write("Hello from Test.aspx.<br>"); %>
- In the C:\Inetpub\Wwwroot\Module directory, create a Global.asax file.
- Paste the following code into Global.asax:
<%@ Import Namespace="MyModule" %>
<script language="C#" runat=server >
protected void MyModule_OnMyEvent(Object src, EventArgs e)
{
Context.Response.Write("Hello from MyModule_OnMyEvent called in Global.asax.<br>");
}
</script>
- Request the Test.aspx page. You should see the following lines of text:
Hello from OnBeginRequest in custom module.
Hello from MyModule_OnMyEvent called in Global.asax.
Hello from Test.aspx.
