Share via

Add a Script Map Handler Mapping (IIS 7)

  • Article

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

When you want a native handler on the Web server to handle requests for a specific file or file name extension, you can create a script map. Native handlers, also known as script engines, are native code .exe or .dll files that respond to specific requests.

Note

Script maps provide backward compatibility with earlier versions of IIS. Executables must be written to the CGI specification, and dynamic-link libraries must support the Internet Server Application Programming Interface (ISAPI) extension interfaces.

If you map a type of request to an .exe file (the script engine), CgiModule will load the associated executable when a request enters the server and it matches the handler mapping. If you map a type of request to a .dll file (the script engine), IsapiModule will load the DLL when a request enters the server and it matches the handler mapping. For example, IIS 7 includes a handler mapping for Active Server Pages (ASP). All requests for .asp files are processed by the asp.dll script engine, which is loaded by IsapiModule because ASP.DLL is an ISAPI extension.

Note

If you configure script maps for executables, make sure that CgiModule is registered and enabled on the Modules page. Likewise, if you configure script maps for DLLs, make sure that IsapiModule is registered and enabled on the Modules page.

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 script map 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 Script Map.

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

  5. In the Executable box, type the full path or browse to the native handler (.dll or .exe file) that processes the request. For example, type systemroot\system32\inetsrv\myHandler.dll.

Note

If you specify the path of an .exe file that has spaces in the path, enclose the path in double quotation marks ("). You can also specify command-line parameters with .exe files. This note does not apply to .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 script map to a native handler, use the following syntax:

appcmd set config /section:handlers /+[name='string',path='string',verb='string',scriptProcessor='string',preCondition='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 with a comma (,) but no spaces. The variable scriptProcessor string is the physical path of the .dll file for the handler. 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 Classic mode for processing managed requests or to specify the version of the .NET Framework to use. For more information about preconditions, see the handlers section in the IIS 7.0: IIS Settings Schema on MSDN.

For example, to add a native handler mapping for a native handler named ImageCopyrightHandler-ClassicMode-2.0 that responds to GET and HEAD requests for .jpg files and processes those requests by using the separate IIS and ASP.NET request-processing pipelines that use the .NET Framework 2.0, type the following at the command prompt, and then press ENTER:

appcmd set config /section:handlers /+[name='ImageCopyrightHandler-ClassicMode-2.0',path='*.jpg',verb='GET,HEAD',scriptProcessor='%windir%\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll',preCondition='classicMode,runtimeVersionv2.0']

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)