How to: Register HTTP Handlers

After you have created a custom HTTP handler class, you must register it in the Web.config file. This enables ASP.NET to call the HTTP handler in order to service requests for resources that have the specified file name extension.

How you register an HTTP handler depends on the version of Internet Information Services (IIS) that hosts your application. For IIS 6.0, you register the handler by using the httpHandlers section of the Web.config file. For IIS 7.0 running in Classic mode, you register the handler in the httpHandlers section, and you map the handler to the Aspnet_isapi.dll file. For IIS 7.0 running in Integrated mode, you register the handler by using the handlers element in the system.WebServer section.

To register an HTTP handler for IIS 6.0

1. Compile the HTTP handler class and copy the resulting assembly to the Bin folder under the application's root folder.

   -or-

   Put the source code for the handler into the application's App_Code folder.

   For an example of an HTTP handler, see Walkthrough: Creating a Synchronous HTTP Handler.

2. In the application's Web.config file, create an httpHandlers section.

   The following 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 example maps all HTTP requests for files that have the file name extension ".SampleFileExtension" to the SampleHandler2 class. In this case, the handler code is in the App_Code folder, so you do not have to specify an assembly.

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

3. Configure IIS to forward the request for the custom file name extension to ASP.NET.

   For more information, see How to: Configure an HTTP Handler Extension in IIS.

To register an HTTP handler for IIS 7.0 running in Classic mode

1. Compile the HTTP handler class and copy the resulting assembly to the Bin folder under the application's root folder.

   -or-

   Put the source code for the handler into the application's App_Code folder.

   For an example of an HTTP handler, see Walkthrough: Creating a Synchronous HTTP Handler.

2. In the application's Web.config file, create an httpHandlers section.

3. Create a system.webServer section inside the configuration element.

4. Create a handlers element inside the system.WebServer section.

   Note

   You must define both an httpHandlers element and a handlers element.

   The following 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>
     <system.webServer>
       <add name=SampleHandler" verb="*" path="SampleHandler.new" 
         Modules="IsapiModule" 
         scriptProcessor="FrameworkPath\aspnet_isapi.dll"
         resourceType="File" />
     </system.webServer>
   </configuration>
   

   Replace FrameworkPath with the correct path to the Aspnet_isapi.dll file.

   The following example maps all HTTP requests for files that have the file name extension ".SampleFileExtension" to the SampleHandler2 class. In this case, the handler code is in the App_Code folder, so you do not have to specify an assembly.

   <configuration>
     <system.web>
       <httpHandlers>
         <add verb="*" path="*.SampleFileExtension" 
            type="SampleHandler2" />
       </httpHandlers>
     <system.web>
     <system.webServer>
       <add name=SampleHandler2" verb="*" path="*.SampleFileExtension" 
         Modules="IsapiModule" 
         scriptProcessor="FrameworkPath\aspnet_isapi.dll"
         resourceType="File" />
     </system.webServer>
   </configuration>
   

   Replace FrameworkPath with the correct path to the Aspnet_isapi.dll file.

   Note

   For IIS 7.0 running in Classic mode, you do not have to separately use IIS Manager to map the file name extension to the Aspnet_isapi.dll file, as you do with IIS 6.0. You can map the extension in the Web.config file.

To register an HTTP handler for IIS 7.0 running in Integrated Mode

1. Compile the HTTP handler class and copy the resulting assembly to the Bin folder under the application's root folder.

   -or-

   Put the source code for the handler into the application's App_Code folder.

   For an example of an HTTP handler, see Walkthrough: Creating a Synchronous HTTP Handler.

2. In the application's Web.config file, create a handlers element in the system.webServer section.

   Note

   Handlers that are defined in the httpHandlers element are not used. If you do not remove the httpHandlers registrations, you must set the validation element’s validateIntegratedModeConfiguration attribute to false in order to avoid errors. The validation element is a child element of the system.webServer element. For more information, see "Disabling the migration error message" in ASP.NET Integration with IIS 7.0.

   The following 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.webServer>
       <handlers>
         <add name="SampleHandler" verb="*" 
           path="SampleHandler.new" 
           type="SampleHandler, SampleHandlerAssembly" 
           resourceType="Unspecified" />
       </handlers>
     </system.webServer>
   </configuration>
   

   Note

   The resourceType attribute performs the same function as the Verify file exists option in IIS manager for IIS 6.0.

   The following example shows how to map all HTTP requests to files with the file name extension ".SampleFileExtension" to the SampleHandler2 HTTP handler class. In this case, the handler code is in the App_Code folder, so you do not have to specify an assembly.

   <configuration>
     <system.webServer>
       <handlers>
         <add name="SampleHandler2" verb="*"
           path="*.SampleFileExtension" 
           type="SampleHandler2" />
           resourceType="Unspecified" />
       <handlers>
     </system.webServer>
   </configuration>
   

   For IIS 7.0 running in Integrated mode, only the registration in the handlers element is required.

   For more information about the IIS web.webServer configuration element, see system.webServer Section Group (IIS Settings Schema) on the MSDN Web site.

   For more information about how to configure a handler for a custom file name extension, see How to: Configure an HTTP Handler Extension in IIS.

See Also

Tasks

How to: Configure an HTTP Handler Extension in IIS

Walkthrough: Creating an Asynchronous HTTP Handler

Walkthrough: Creating a Synchronous HTTP Handler

Concepts

ASP.NET Application Life Cycle Overview for IIS 5.0 and 6.0

ASP.NET Application Life Cycle Overview for IIS 7.0