How to: Register HTTP Handlers

After you have created a custom HTTP handler class, you must register it in the Web.config file. This allows ASP.NET to call the handler to service requests made to resources with the file name extension that you want the HTTP handler to process.

Register an HTTP Handler in the Web.config File

In order for ASP.NET to send requests to a custom HTTP handler, you must register the file name extension with the custom HTTP handler. You do this in your application's Web.config file.

To register an HTTP handler

1. Compile the .NET class for the HTTP handler and copy the resulting assembly to the Bin directory under the application's virtual root, or put the source code for the handler into your application's App_Code folder.

   For one example of an HTTP handler, see How to: Create Synchronous HTTP Handlers.

2. Register the HTTP handler in the application's Web.config file by creating an httpHandlers Element (ASP.NET Settings Schema) section.

   The following code example shows how to register an HTTP handler that responds to requests for the SampleHandler.new resource. The handler is defined as the class SampleHandler in the assembly SampleHandlerAssembly.

   <configuration>
     <system.web>
       <httpHandlers>
         <add verb="*" path="SampleHandler.new" 
           type="SampleHandler, SampleHandlerAssembly" />
       </httpHandlers>
     <system.web>
   </configuration>
   

   The following code example maps all HTTP requests to files with the file name extension of SampleFileExtension to the SampleHandler2 custom HTTP handler class. In this case, the handler code is in the App_Code directory, so you do not need to specify an assembly.

   <configuration>
     <system.web>
       <httpHandlers>
         <add verb="*" path="*.SampleFileExtension" 
            type="SampleHandler2 " />
       </httpHandlers>
     <system.web>
   </configuration>
   

Configuring IIS for an HTTP Handler Extension

Internet Information Services (IIS) will only pass requests for certain file types to ASP.NET to service. By default, files with file name extensions, such as .aspx, .ascx, .asmx, and .ashx are already mapped to the ASP.NET ISAPI extension (Aspnet_isapi.dll). However, to have IIS pass custom file name extensions to ASP.NET, you must register the extensions in IIS. For more information, see ASP.NET Application Life Cycle Overview.

To map a file name extension in IIS

1. In Windows, open Internet Information Services (IIS) Manager.

2. Open the node for your computer, open the Web Sites node, and then open the Default Web Site node.

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

4. Click the Directory tab (or the Virtual Directory tab in IIS 6.0), and then click Configuration.

5. On the Mappings tab, click Add and create a new association for the file name extension that you want IIS to forward to ASP.NET.

   Note
   Click the Edit button to view an existing association to determine what value to use for the executable file.

6. If you want your handler to run regardless of whether a file exists with the requested file name extension, clear the Verify that file exists check box.

See Also

Tasks

How to: Create an Asynchronous HTTP Handler
How to: Create Synchronous HTTP Handlers

Concepts

Introduction to HTTP Handlers
ASP.NET Application Life Cycle Overview