Walkthrough: Creating and Registering HTTP Handler Factories

Article
12/04/2014

The IHttpHandlerFactory interface creates and manages HTTP handlers for processing requests. Therefore, you can create a class that implements the IHttpHandlerFactory interface, and then use that class as an HTTP handler.

Creating handlers in this manner can give you finer control over the processing of an HTTP request. It lets you map a URL to an HTTP handler factory that creates different handlers based on a set of conditions. For example, with an HTTP handler factory you can create a limited number of HTTP handler objects that access expensive or limited resources, such as database connections. You can then reuse those handler objects in future requests.

In this walkthrough, you will create an HTTP handler factory that creates two handlers for resources that are identified with the extension .sample. One handler works with resources during an HTTP GET request, and the other handler works with HTTP POST requests. The first handler is an instance of the handler described in Walkthrough: Creating a Synchronous HTTP Handler. The second handler is an instance of the handler described in Walkthrough: Creating an Asynchronous HTTP Handler.

Tasks illustrated in this walkthrough include the following:

How to create the code for an HTTP handler factory class.
How to register the handler factory in the Web.config file and map the .sample file name extension to it.
How to map the .sample file name extension to ASP.NET In Internet Information Services (IIS).

Prequisites

In order to complete this walkthrough, you will need:

Visual Studio or Visual Web Developer.
An ASP.NET Web site that you can run by using IIS.
IIS 6.0 or IIS 7.0.

Creating a Custom HTTP Handler Factory

To begin, you will create a handler factory class.

To create an HTTP handler factory class

If the ASP.NET Web site does not already have an App_Code folder, create one under the root of the site.
In the App_Code directory, create a class named HelloWorldHandler.

Add the following code to the class file.

Imports System
Imports System.Web

Class HandlerFactory
    Implements IHttpHandlerFactory

    Public Function GetHandler(ByVal context As HttpContext, _
            ByVal requestType As String, ByVal url As [String],_ 
            ByVal pathTranslated As [String]) As IHttpHandler _
            Implements IHttpHandlerFactory.GetHandler
        Dim handlerToReturn As IHttpHandler
        Dim requestType as String = _      
            context.Request.RequestType.ToLower()
        If "get" = requestType Then
            handlerToReturn = New HelloWorldHandler()
        Else
            If "post" = requestType Then
                handlerToReturn = New HelloWorldAsyncHandler()
            Else
                handlerToReturn = Nothing
            End If
        End If
        Return handlerToReturn
    End Function

    Public Sub ReleaseHandler(ByVal handler As IHttpHandler) _
        Implements IHttpHandlerFactory.ReleaseHandler
    End Sub

    Public ReadOnly Property IsReusable() As Boolean
        Get
            Return False
        End Get
    End Property
End Class

using System;
using System.Web;

class HandlerFactory : IHttpHandlerFactory
{
    public IHttpHandler GetHandler(HttpContext context, 
        string requestType, String url, String pathTranslated)
    {
        IHttpHandler handlerToReturn;
        if ("get" == context.Request.RequestType.ToLower())
        {
            handlerToReturn = new HelloWorldHandler();
        }
        else if ("post" == context.Request.RequestType.ToLower())
        {
            handlerToReturn = new HelloWorldAsyncHandler();
        }
        else
        {
            handlerToReturn = null;
        }
        return handlerToReturn;
    }
    public void ReleaseHandler(IHttpHandler handler)
    {
    }
    public bool IsReusable
    {
        get
        {
            return false;
        }
    }
}

The code implements the GetHandler method of the IHttpHandlerFactory interface. If the request is a GET request, the method returns the synchronous handler interface. If the request is a POST request, it returns the asynchronous handler interface.

Creating Custom HTTP Handlers

The custom HTTP handler factory returns either the synchronous handler described in Walkthrough: Creating a Synchronous HTTP Handler, or the asynchronous handler described in Walkthrough: Creating an Asynchronous HTTP Handler. You must create both the synchronous HelloWorldHandler class and the asynchronous HelloWorldAsyncHandler class in order for the custom HTTP handler factory to be able to return those handlers.

To create the HelloWorldHandler and the HelloWorldAsyncHandler classes

In the Web site's App_Code directory, create a class named HelloWorldHandler.
Add the code from Walkthrough: Creating a Synchronous HTTP Handler to the class file.
In the Web site's App_Code directory, create a class named HelloWorldAsyncHandler.
Add the code from Walkthrough: Creating an Asynchronous HTTP Handler to the class file.

Registering the Custom HTTP Handler Factory in IIS 6.0

After you have created the custom HTTP handler factory class, you must register it in the application's Web.config file. This enables ASP.NET to use the handler factory class to service requests made to resources with the .sample file name extension.

There are different procedures for registering the handler, depending on whether you are working with IIS 6.0 or IIS 7.0. This section describes how to register a handler in IIS 6.0. The next section describes how to register a handler in IIS 7.0.

To register the handler factory in IIS 6.0

If the Web site does not already have a Web.config file, create one under the root of the site.
Add the following highlighted element to the Web.config file.
```
<configuration>
  <system.web>
<httpHandlers><add verb="GET,POST" path="*.sample"type="HandlerFactory" /></httpHandlers>
  </system.web>
</configuration>
```
The code registers the handler factory with the class name and the handler name of HandlerFactory.
Register an application extension mapping for the .sample file name extension by using IIS Manager. For more information, see How to: Configure an HTTP Handler Extension in IIS.

Registering the Custom HTTP Handler Factory in IIS 7.0

In IIS 7.0, an application can run in either Classic or Integrated mode. In Classic mode, requests are processed much the same way as they are in IIS 6.0. In Integrated mode, IIS 7.0 manages requests by using a pipeline that enables it to share requests, modules, and other features with ASP.NET.

For IIS 7.0, you register the handler factory either in the Web.config file or in IIS Manager. Because administration is centralized in IIS 7.0, changes in an application's Web.config file are reflected in the IIS Manager interface for the application and vice versa. In the procedures that follow, the handlers are registered in the Web.config file.

To register the handler factory in IIS 7.0 running in Classic mode

If the Web site does not already have a Web.config file, create one.
Add the following highlighted element to the Web.config file.

Note

Substitute the correct path for the aspnet_isapi.dll file. The .dll file is in the folder where the .NET Framework is installed. By default this is C:\WINDOWS\Microsoft.NET\Framework\version.
```
<configuration>
  <system.webServer>
<handlers><add  verb="GET,POST" path="*.sample"name="HandlerFactory"type="HandlerFactory"modules="IsapiModule"/>scriptProcessor="%path%\aspnet_isapi.dll"</handlers>
  </system.webServer>
</configuration>
```
The configuration element registers the custom handler factory by class name and maps the .sample file name extension to that handler.

Note

Because you are registering a custom file name extension, you register the handler in both the handlers section and the httpHandlers section. In Classic mode, for backward compatibility, the handler is specified as an ISAPI module by using the modules attribute. The path of the ASP.NET ISAPI dll is specified by using the scriptProcessor attribute. The name attribute is required in the handlers section.

To register the handler factory in IIS 7.0 running in Integrated mode

If the Web site does not already have a Web.config file, create one under the root of the site.
Add the following highlighted element to the Web.config file.
```
<configuration>
  <system.webServer>
<handlers><add verb="GET,POST" path="*.sample" name="HandlerFactory"type="HandlerFactory"/></handlers>
  </system.webServer>
</configuration>
```
The configuration element registers the custom handler factory by class name and maps the .sample file name extension to that handler.

Note

The registration is done in the handlers section, but not in the httpHandlers section. The name attribute is required.

Testing the Custom HTTP Handler Factory

After you have created and registered your custom HTTP handler factory, you can test it.

To test the custom HTTP handler factory

Create an HTML page (with a file name extension of .htm) in your application.

In the body section of the page, add the following markup.

<form action="Sample.sample" method="get">
  <input type="submit" value="Submit to Sample.sample via Get" />
</form>
<br />
<form action="Sample.sample" method="post">
  <input type="submit" value="Submit to Sample.sample via Post" />
</form>

Request the HTML page in a browser.
Click one of the buttons.

When you click the first button, the HTTP handler factory responds to the request by creating and calling a synchronous HTTP handler. When you click the second button, the HTTP handler factory responds to the request by creating and calling an asynchronous HTTP handler.