httpHandlers Element (ASP.NET Settings Schema)

  • Article

Maps incoming requests to the appropriate handler according to the URL and the HTTP verb that is specified in the request. This element can be declared at any level in the configuration hierarchy.

<configuration> Element
  system.web Element (ASP.NET Settings Schema)
    httpHandlers Element (ASP.NET Settings Schema)

<httpHandlers>
   <add... />
   <remove... />
   <clear/>
</httpHandlers>

Attributes and Elements

The following sections describe attributes, child elements, and parent elements.

Attributes

None.

Child Elements

Subtag

Description

add

Optional element.

Specifies verb/path mapping to a handler.

clear

Optional element.

Removes all handler mappings that are currently configured or inherited.

remove

Optional element.

Removes a verb/path mapping to a handler. The remove directive must exactly match the verb/path combination of a previous add directive. Wildcard characters are not supported.

Parent Elements

Element

Description

configuration

Specifies the root element in every configuration file that is used by the common language runtime and the .NET Framework applications.

system.web

Specifies the root element for the ASP.NET configuration section.

Remarks

The <httpHandlers> settings are inherited by the application subdirectories.

The <add> directives are processed in top-down, sequential order. If two or more <add> elements specify the same verb/path combination, the final <add> overrides all others.

Note

The Microsoft Internet Information Services (IIS) has its own model for mapping extensions to ISAPIs. For the mapping between a given application extension and its handler to take effect, the extension must be mapped in IIS to ASP.NET ISAPI. For nonstandard extension, such as custom extensions, you must configure IIS accordingly.

Default Configuration

The following default httpHandlers element is configured in the Machine.config file in the .NET Framework version 2.0.

<httpHandlers />

The following default httpHandlers element is configured in the Machine.config file in the .NET Framework version 1.1.

Note

System.Web.HttpForbiddenHandler is an internal type that issues the HTTP 403 error "Forbidden: Access is denied" when an attempt is made to access a forbidden resource.

System.Web.StaticFileHandler is another internal type that handles access to specified files. In case of access issues it generates one of the following errors: HTTP 401 error "Unauthorized"; HTTP 403 error "Forbidden: Access is denied"; or HTTP 404 error "File or directory not found".

<httpHandlers>
     <add verb="*" path="*.vjsproj" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.java" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.jsl" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="trace.axd" type="System.Web.Handlers.TraceHandler"/>
     <add verb="*" path="*.aspx" type="System.Web.UI.PageHandlerFactory"/>
     <add verb="*" path="*.ashx" type="System.Web.UI.SimpleHandlerFactory"/>
     <add verb="*" path="*.asmx" type="System.Web.Services.Protocols.WebServiceHandlerFactory,
System.Web.Services, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
          validate="false"/>
     <add verb="*" path="*.rem" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="false"/>
     <add verb="*" path="*.soap" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=1.0.5000.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="false"/>
     <add verb="*" path="*.asax" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.ascx" type="System.Web.HttpForbiddenHandler"/>
     <add verb="GET,HEAD" path="*.dll.config" type="System.Web.StaticFileHandler"/>
     <add verb="GET,HEAD" path="*.exe.config" type="System.Web.StaticFileHandler"/>
     <add verb="*" path="*.config" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.cs" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.csproj" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.vb" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.vbproj" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.webinfo" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.asp" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.licx" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.resx" type="System.Web.HttpForbiddenHandler"/>
     <add verb="*" path="*.resources" type="System.Web.HttpForbiddenHandler"/>
     <add verb="GET,HEAD" path="*" type="System.Web.StaticFileHandler"/>
     <add verb="*" path="*" type="System.Web.HttpMethodNotAllowedHandler"/>
</httpHandlers>

The following default httpHandlers element is configured in the Machine.config file in the .NET Framework version 1.0.

<httpHandlers>
     <add verb="*" path="trace.axd" type="System.Web.Handlers.TraceHandler" />
     <add verb="*" path="*.aspx" type="System.Web.UI.PageHandlerFactory" />
     <add verb="*" path="*.ashx" type="System.Web.UI.SimpleHandlerFactory" />
     <add verb="*" path="*.asmx" type="System.Web.Services.Protocols.WebServiceHandlerFactory,
System.Web.Services, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" 
          validate="false"/> 
     <add verb="*" path="*.rem" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="false"/>
     <add verb="*" path="*.soap" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="false"/>
     <add verb="*" path="*.asax" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.ascx" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.config" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.cs" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.csproj" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.vb" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.vbproj" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.webinfo" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.asp" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.licx" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.resx" type="System.Web.HttpForbiddenHandler" />
     <add verb="*" path="*.resources" type="System.Web.HttpForbiddenHandler" />
     <add verb="GET,HEAD" path="*" type="System.Web.StaticFileHandler" />
     <add verb="*" path="*" type="System.Web.HttpMethodNotAllowedHandler" />
 </httpHandlers>

The following default httpHandlers element is configured in the root Web.config file in the .NET Framework 2.0.

<httpHandlers>
     <add path="trace.axd" verb="*" type="System.Web.Handlers.TraceHandler" validate="True" />
     <add path="WebResource.axd" verb="GET" type="System.Web.Handlers.AssemblyResourceLoader" 
          validate="True" />
     <add path="*.axd" verb="*" type="System.Web.HttpNotFoundHandler" validate="True" />
     <add path="*.aspx" verb="*" type="System.Web.UI.PageHandlerFactory" validate="True" />
     <add path="*.ashx" verb="*" type="System.Web.UI.SimpleHandlerFactory" validate="True" />
     <add path="*.asmx" verb="*" type="System.Web.Services.Protocols.WebServiceHandlerFactory, 
System.Web.Services, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a" validate="False" />
     <add path="*.rem" verb="*" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="False" />
     <add path="*.soap" verb="*" type="System.Runtime.Remoting.Channels.Http.HttpRemotingHandlerFactory,
System.Runtime.Remoting, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" 
          validate="False" />
     <add path="*.asax" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.ascx" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.master" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.skin" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.browser" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.sitemap" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.dll.config" verb="GET,HEAD" type="System.Web.StaticFileHandler" validate="True" />
     <add path="*.exe.config" verb="GET,HEAD" type="System.Web.StaticFileHandler" validate="True" />
     <add path="*.config" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.cs" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.csproj" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.vb" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.vbproj" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.webinfo" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.licx" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.resx" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.resources" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.mdb" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.vjsproj" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.java" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.jsl" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.ldb" verb="*" type="System.Web.HttpForbiddenHandler"  validate="True" />
     <add path="*.dsdgm" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.ssdgm" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.lsad" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.ssmap" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.cd" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.dsprototype" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.lsaprototype" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.sdm" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.sdmDocument" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.mdf" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*.ldf" verb="*" type="System.Web.HttpForbiddenHandler" validate="True" />
     <add path="*" verb="GET,HEAD,POST" type="System.Web.DefaultHttpHandler" validate="True" />
     <add path="*" verb="*" type="System.Web.HttpMethodNotAllowedHandler" validate="True" />
</httpHandlers>

Example

The following example demonstrates how to do the following:

  • Map all HTTP requests for files with the file name extension .New to the class MyHandler.New

  • Map HTTP GET and HEAD requests for files with the file name extension .MyNewFileExtension to the class MyHandler.MNFEHandler.

Both classes are in the assembly MyHandler that is in the file MyHandler.dll.

<configuration>
   <system.web>
      <httpHandlers>
         <add verb="*" 
              path="*.New" 
              type="MyHandler.New,MyHandler"/>
         <add verb="GET,HEAD" 
              path="*.MyNewFileExtension" 
              type="MyHandler.MNFEHandler,MyHandler.dll"/>
     </httpHandlers>
   </system.web>
</configuration>

Element Information

Configuration section handler

System.Web.Configuration.HttpHandlersSection

Configuration member

SystemWebSectionGroup.HttpHandlers

Configurable locations

Machine.config

Root-level Web.config

Application-level Web.config

Virtual or physical directory–level Web.config

Requirements

Microsoft Internet Information Services (IIS) version 5.0, 5.1, or 6.0

The .NET Framework version 1.0, 1.1, or 2.0

Microsoft Visual Studio 2003 or Visual Studio 2005

See Also

Tasks

How to: Lock ASP.NET Configuration Settings

Reference

system.web Element (ASP.NET Settings Schema)

<configuration> Element

add Element for httpHandlers (ASP.NET Settings Schema)

clear Element for httpHandlers (ASP.NET Settings Schema)

remove Element for httpHandlers (ASP.NET Settings Schema)

System.Configuration

System.Web.Configuration

Concepts

ASP.NET Configuration Overview

ASP.NET Web Server Controls and Browser Capabilities

Securing ASP.NET Configuration

ASP.NET Configuration Scenarios

Other Resources

ASP.NET Configuration Files

ASP.NET Configuration Settings

General Configuration Settings (ASP.NET)

ASP.NET Configuration API