Welcome Sign in
Skip Navigation Links
Visual Studio 2005 Developer Center
Click to Rate and Give Feedback
MSDN
MSDN Library
Visual Studio 2005
Visual Studio
Web Sites
Learning More
 How to: Create Synchronous HTTP Han...
This page is specific to
Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:
ASP.NET 
How to: Create Synchronous HTTP Handlers 

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.

    Visual Basic
    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

    C#
    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:

    http://localhost/SampleApplication/test.sample

    The text defined in the HelloWorldHandler class is displayed.

See Also

Tags What's this?: Add a tag
Community Content   What is Community Content?
Add new content RSS  Annotations
Getting this sample to work      Greg Gum   |   Edit   |  

After spending some free time getting this sample to work, I want to point out a few things that may be helpful to others in getting the sample to work:

1. When mapping your .Sample extension in IIS, you are mapping it to ASPNET_ISAPI.dll, *NOT* to your dll.

2. Make sure you take note of *UNCHECKING* the "Verify file exists" checkbox, or you will get a 404 error when you try to navigate to test.sample.

3. It is *NOT* necessary to compile your handler into a DLL and upload the DLL. This is taken care of automatically by ASP.NET as long as the class is available.

4. If you do compile your code to .dll, put it in a bin subdirectory, and include the assembly name in the config file (in the above example, just the class name is used as it's not in a dll) Thus the entry looks like this:

<add verb="*" path="*.sample" 
                  type="HelloWorldHandler, HelloWorldHandler"/>

Greg

Tags What's this?: Add a tag
Flag as ContentBug
Processing
© 2008 Microsoft Corporation. All rights reserved. Terms of Use  |  Trademarks  |  Privacy Statement
Page view tracker