Add a Module Handler Mapping (IIS 7)

  • Article

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

When you want a native module on the Web server to handle requests for a specific file or file name extension, you can create a module handler mapping. For example, IIS 7 maps all requests for .exe files to CgiModule, so that module is called when a user requests a file that has the .exe file name extension.

Prerequisites

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 module 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 Module Mapping.

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

  5. In the Module list, select the module that you want to mapping to use.

  6. Optionally, in the Executable box, type a path of the .dll or .exe file when the module you selected in the Module box requires an executable to run, such as the FastCGI module. You can also click the browse button (...) to locate the executable.

Note

After you click OK to add or save the handler mapping, the executable must be added to the ISAPI and CGI Restrictions list to enable it to run.

  1. If you specify an .exe file in the Executable box, you can also type optional command-line parameters after the path. Command-line parameters are not supported for .dll files.

Note

If you specify a path for an .exe file, and the path contains spaces, you must enclose the path with double quotation marks ("). For example, type "c:\files\handler files\handler.exe". This is not required for .dll files.

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

  2. 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.

  3. Click OK.

  4. 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 module, use the following syntax:

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

The variable name string is the name of the native 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 modules string is the name of the module or a list of modules to processes requests that match the handler mapping.

For example, to add a module mapping for a module named ImageCopyrightModule that responds to GET and HEAD requests for .jpg files and processes those requests by using the IIS 7 IsapiModule, type the following at the command prompt, and then press ENTER:

appcmd set config /section:handlers /+[name='ImageCopyrightHandler',path='*.jpg',verb='GET,HEAD',modules='IsapiModule']

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

Configuration

The procedure in this topic affects the following configuration elements:

<handlers>

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

WMI

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

  • HandlersSection class (IIS)

  • HttpHandlersSection 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

Concepts

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