Microsoft ASP.NET QuickStarts Tutorial

HTTP Handlers and Factories

  Overview
  Configuring HTTP Handlers and Factories
  Creating a Custom HTTP Handler
  Section Summary

ASP.NET provides a low-level request/response API that enables developers to use .NET Framework classes to service incoming HTTP requests. Developers accomplish this by authoring classes that support the System.Web.IHTTPHandler interface and implement the ProcessRequest() method. Handlers are often useful when the services provided by the high-level page framework abstraction are not required for processing the HTTP request. Common uses of handlers include filters and CGI-like applications, especially those that return binary data.

Each incoming HTTP request received by ASP.NET is ultimately processed by a specific instance of a class that implements IHTTPHandler. IHttpHandlerFactory provides the infrastructure that handles the actual resolution of URL requests to IHttpHandler instances. In addition to the default IHttpHandlerFactory classes provided by ASP.NET, developers can optionally create and register factories to support rich request resolution and activation scenarios.

Configuring HTTP Handlers and Factories

HTTP handlers and factories are declared in the ASP.NET configuration as part of a web.config file. ASP.NET defines an <httphandlers> configuration section where handlers and factories can be added and removed. Settings for HttpHandlerFactory and HttpHandler are inherited by subdirectories.

For example, ASP.NET maps all requests for .aspx files to the PageHandlerFactory class in the global machine.config file:

<httphandlers>
  ...
  <add verb="*" path="*.aspx" type="System.Web.UI.PageHandlerFactory,System.Web" />
  ...
</httphandlers>

Creating a Custom HTTP Handler

The following sample creates a custom HttpHandler that handles all requests to "SimpleHandler.aspx".

VB SimpleHandler

[Run Sample] | [View Source]

A custom HTTP handler can be created by implementing the IHttpHandler interface, which contains only two methods. By calling IsReusable, an HTTP factory can query a handler to determine whether the same instance can be used to service multiple requests. The ProcessRequest method takes an HttpContext instance as a parameter, which gives it access to the Request and Response intrinsics. In the following sample, request data is ignored and a constant string is sent as a response to the client.


Public Class SimpleHandler : Inherits IHttpHandler
  Public Sub ProcessRequest(context As HttpContext)
    context.Response.Write("Hello World!")
  End Sub

  Public Function IsReusable() As Boolean
    Return(True)
  End Function
End Class

After placing the compiled handler assembly in the application's \bin directory, the handler class can be specified as a target for requests. In this case, all requests for "SimpleHandler.aspx" will be routed to an instance of the SimpleHandler class, which lives in the namespace Acme.SimpleHandler.

Section Summary

HTTP Handlers and factories are the backbone of the ASP.NET page framework.
Factories assign each request to one handler, which processes the request.
Factories and handlers are defined in the web.config file. Settings for factories are inherited by subdirectories.
To create a custom handler, implement IHttpHandler and add the class in the <httphandlers> section of the web.config in the directory.