How to: Create Synchronous HTTP Handlers

  • Article

This topic illustrates the code for an HTTP handler that performs synchronous processing of requests for resources in an ASP.NET application whose URL ends with .sample. The code example illustrates the following:

  • The code for an HTTP handler class. The class must implement the ProcessRequest method and the IsReusable property.

  • The elements that are required in a Web.config file to register the handler and map the .sample file name extension to it.

  • In Internet Information Services (IIS), how to map the .sample file name extension to ASP.NET.

NoteNote

The ASP.NET Development Server will serve the request for the new resource after the configuration file is changed to include a reference to the new handler. To enable IIS to serve the request, see the procedure below.

When users request a resource whose URL ends in .sample, the Web server forwards the request to ASP.NET. ASP.NET then calls the HTTP handler, which returns a response. The response is created dynamically by the handler; there is no need for a file with the file name extension .sample to exist. For more information about how ASP.NET interacts with the Web server, see ASP.NET Life Cycle.

To create the custom HelloWorldHandler HTTP handler class

  1. In your Web site's App_Code directory, create a class named HelloWorldHandler.

  2. Add the following code to your class file.

    Imports System.Web

Public Class HelloWorldHandler
    Implements IHttpHandler

    Public Sub ProcessRequest(ByVal context As _
            System.Web.HttpContext) Implements _
            System.Web.IHttpHandler.ProcessRequest
        Dim request As HttpRequest = context.Request
        Dim response As HttpResponse = context.Response
        ' This handler is called whenever a file ending 
        ' in .sample is requested. A file with that extension
        ' does not need to exist.
        response.Write("<html>")
        response.Write("<body>")
        response.Write("<h1>Hello from a synchronous custom HTTP handler.</h1>")
        response.Write("</body>")
        response.Write("</html>")
    End Sub

    Public ReadOnly Property IsReusable() As Boolean _
            Implements System.Web.IHttpHandler.IsReusable
        Get
            Return False
        End Get
    End Property
End Class

    using System.Web;
public class HelloWorldHandler : IHttpHandler
{
    public HelloWorldHandler()
    {
    }
    public void ProcessRequest(HttpContext context)
    {
        HttpRequest Request = context.Request;
        HttpResponse Response = context.Response;
        // This handler is called whenever a file ending 
        // in .sample is requested. A file with that extension
        // does not need to exist.
        Response.Write("<html>");
        Response.Write("<body>");
        Response.Write("<h1>Hello from a synchronous custom HTTP handler.</h1>");
        Response.Write("</body>");
        Response.Write("</html>");
    }
    public bool IsReusable
    {
        // To enable pooling, return true here.
        // This keeps the handler in memory.
        get { return false; }
    }
}

    The code implements the ProcessRequest method and writes out a string to the Response property of the current HttpContext object.

Registering a Custom HTTP Handler

After you have created the custom HTTP handler class, you must register it in the application's Web.config file. This allows ASP.NET to find the handler when ASP.NET receives requests made to resources whose URL ends with .sample.

To register a custom HTTP handler in the Web.config file

  1. Add a Web.config file to your Web site if one does not already exist.

  2. Add the following highlighted element to your Web.config file.

    <configuration>
    <system.web>
        <httpHandlers>            <add verb="*" path="*.sample"                   type="HelloWorldHandler"/>        </httpHandlers>
    </system.web>
</configuration>

    The code registers your custom handler by class name and maps the .sample file name extension to that handler.

Configuring IIS 6.0 for an HTTP Handler Extension

IIS passes requests for only certain file types to ASP.NET to service. By default, files with file name extensions such as .aspx, .ascx, .asmx, are already mapped in IIS 6.0 to the ASP.NET ISAPI extension (Aspnet_isapi.dll). However, if you want ASP.NET to handle custom URL extensions, you must map the extensions in IIS. For more information, see ASP.NET Life Cycle.

To map the .sample file name extension to ASP.NET in IIS 6.0

  1. Open Internet Information Services (IIS) Manager.

  2. Right-click the name of your application, and then click Properties.

    NoteNote

    For instructions for creating an ASP.NET application, see How to: Create and Configure Local ASP.NET Web Sites in IIS.

  3. Click the Virtual Directory tab, and then click Configuration.

  4. On the Mappings tab, click Add.

    The Add/Edit Application Extension Mapping dialog box is displayed.

  5. In the Executable box, type or browse to the file Aspnet_isapi.dll. By default, the file is in the following location.

    %windows%\Microsoft.NET\Framework\version\
    NoteNote

    You can get the complete path and file name from other mappings, such as the mapping to .aspx files.

  6. In the Extension box, type .sample.

  7. Clear the Verify that file exists check box.

  8. Click OK and then close IIS Manager.

Testing the Custom HTTP Handler

After you have created and registered your custom HTTP handler, you can test it by requesting a resource that has a .sample file name extension.

To test your custom HTTP handler

  • In your browser, enter a URL that points to your Web application and that ends in .sample, such as the following:

    https://localhost/SampleApplication/test.sample

    The text defined in the HelloWorldHandler class is displayed.

See Also

Tasks

How to: Create an Asynchronous HTTP Handler

Concepts

Introduction to HTTP Handlers
ASP.NET Application Life Cycle Overview

Other Resources

ASP.NET Life Cycle