Add a Managed Handler Mapping (IIS 7)

Applies To: Windows 7, Windows Server 2008, Windows Server 2008 R2, Windows Vista

When you want a managed handler on the Web server to handle requests for a specific file or file name extension, you can create a managed handler mapping. Managed handlers are written in managed code and respond to specific requests on the Web server. For example, the PageHandlerFactory-Integrated handler mapping specifies that the System.Web.UI.PageHandlerFactory handler process requests for .aspx files.


By default, when you add a managed handler, the handler will run only in application pools configured to use Integrated mode. However, if you want to run the handler in application pools configured to use Classic mode, you must add the handler to the <httpHandlers> section in System.web from a tool, such as Appcmd.exe.


For information about the levels at which you can perform this procedure, and the modules, handlers, and permissions that are required to perform this procedure, see Handler Mappings Feature Requirements (IIS 7).

Exceptions to feature requirements

  • None

To add a managed handler mapping

You can perform this procedure by using the user interface (UI), by running Appcmd.exe commands in a command-line window, by editing configuration files directly, or by writing WMI scripts.

User Interface

To use the UI

  1. Open IIS Manager and navigate to the level you want to manage. For information about opening IIS Manager, see Open IIS Manager (IIS 7). For information about navigating to locations in the UI, see Navigation in IIS Manager (IIS 7).

  2. In Features View, on the server, site, or applicationHome page, double-click Handler Mappings.

  3. On the Handler Mappings page, in the Actions pane, click Add Managed Handler.

  4. In the Request path box, type a file name extension or a file name with extension.

  5. In the Type box, type the managed type for the handler. For example, type System.Web.Handlers.

  6. In the Name box, type a friendly name for the handler mapping.

  7. Optionally, click Request Restrictions and configure restrictions if you want the handler to process requests only for specific resource types or verbs, and then click OK.

  8. Click OK.

  9. Optionally, on the Handler Mappings page, select a handler to lock or unlock it. When you lock a handler mapping, it cannot be overridden at lower levels in the configuration. Select a handler mapping in the list, and then in the Actions pane, click Lock or Unlock.

Command Line

To add a mapping to a managed handler, use the following syntax:

appcmd set config /section:handlers /+[name='string',path='string',verb='string',type='string',preCondition='string']

The variable name string is the name of the managed handler, and **path **string is the file name extension or file name that the handler processes. The variable **verb **string is the HTTP verb or list of HTTP verbs to which to restrict the handler, such as GET, HEAD, POST, DEBUG. If you specify more than one verb for **verb **string, separate each verb in the list by using a comma but no spaces. The variable type string is the managed type for the handler, such as System.Web.Handlers. The variable preCondition string is rule or list of rules under which the handler will respond, such as for requests made to application pools that are configured to use Integrated mode or for 32-bit requests. For more information about preconditions, see the handlers section in the IIS 7.0: IIS Settings Schema on MSDN.

For example, to add a managed handler mapping for a managed handler named ImageCopyrightHandler-Integrated that responds to GET and HEAD requests for .jpg files and processes those requests by using the IIS 7 integrated pipeline, type the following at the command prompt, and then press ENTER:

appcmd set config /section:handlers /+[name='ImageCopyrightHandler-Integrated',path='*.jpg',verb='GET,HEAD',type='System.Web.Handlers',preCondition='integratedMode']

For more information about Appcmd.exe, see Appcmd.exe (IIS 7).


The procedure in this topic affects the following configuration elements:


For more information about IIS 7 configuration, see IIS 7.0: IIS Settings Schema on MSDN.


Use the following WMI classes, methods, or properties to perform this procedure:

  • ModulesSection class (IIS)

  • HttpModulesSection class (ASP.NET)

For more information about WMI and IIS, see Windows Management Instrumentation (WMI) in IIS 7. For more information about the classes, methods, or properties associated with this procedure, see the IIS WMI Provider Reference on the MSDN site.

See Also


Configuring Handler Mappings in IIS 7
Configure Request Restrictions for a Handler Mapping (IIS 7)