Export (0) Print
Expand All
0 out of 4 rated this helpful - Rate this topic

Handler Mappings

Published: February 29, 2012

Updated: February 29, 2012

Applies To: Windows Server 2012, Windows Server 2012 R2



Use the Handler Mappings feature page to manage a list of handlers that process requests for specific file types.

Sort the list by clicking one of the feature page column headings or select a value from the Group by drop-down list to group similar items.

Related scenarios

In this document

  1. UI Elements for Handler Mappings

  2. Add or Edit Managed Handler Dialog Box

  3. Add or Edit Script Map Dialog Box

  4. Add or Edit Wildcard Script Map Dialog Box

  5. Add or Edit Module Mapping Dialog Box

  6. Request Restrictions Dialog Box

  7. Edit Feature Permissions Dialog Box

The following tables describe the UI elements that are available on the feature page and in the Actions pane.

 

Element Name Description

Name

Displays the name of the handler mapping.

Path

Displays the file name or file name extension for which the handler processes a response. The value can be either a specific file name, such as WebResource.axd, or a wildcard (*) with a specific extension, such as *.exe.

State

Displays whether the handler is enabled or disabled based on the access policy set in the Edit Feature Permissions dialog box and the required access setting that is specified by the handler mapping. If a handler requires a type of access that is not enabled in the access policy at that level, the handler is disabled.

Path Type

Displays one of the following values for the type of path to which the handler is mapped:

  • Unspecified, if the mapping does not apply to a specific path type.

  • File, if the mapping applies to a file.

  • Directory, if the mapping applies to a directory.

  • File or Directory, if the mapping is for either a file or a directory.

Handler

Displays the module, such as IsapiModule, or managed type, such as System.Web.Handlers.TraceHandler, that responds to the request as specified in the mapping.

Entry Type

Displays whether the item is local or inherited. Local items are read from the current configuration file, and inherited items are read from a parent configuration file.

 

Element Name Description

Add Managed Handler

Opens the Add Managed Handler dialog box in which you can add a mapping to a managed code handler.

Add Script Map

Opens the Add Script Map dialog box in which you can add a mapping to a script processor.

Add Wildcard Script Map

Opens the Add Wildcard Script Map dialog box in which you can add a handler mapping to handle every file name extension.

Add Module Mapping

Opens the Add Module Mapping dialog box in which you can add a mapping to a module.

Edit

Opens an edit dialog box from which you can edit the selected handler mapping.

Rename

Enables the Name field so you can change the friendly name of the selected handler mapping.

noteNote
This action is available only at the server level.

Lock

Locks the selected handler mapping so it cannot be overridden at lower levels in configuration.

noteNote
This action is available only at the server level.

Unlock

Unlocks the selected handler mapping so it can be overridden at lower levels in configuration.

noteNote
This action is available only at the server level.

Remove

Removes the item that is selected from the list on the feature page.

Edit Feature Permissions

Opens the Edit Feature Permissions dialog box in which you can configure permissions that apply to the entire Handler Mappings feature.

Revert to Inherited

Reverts the feature to inherit settings from the parent configuration. This option deletes local configuration settings, including items from the list, for this feature. This action is not available at the server level.

View Ordered List

Displays the list in order of configuration. When you select the ordered list format, you can only move items up and down in the list. Other actions in the Actions pane do not appear until you select the unordered list format.

Move Up

Moves up a selected item in the list. This action is available only when viewing items in the ordered list format.

noteNote
When items in the list are reordered at a child level, the child no longer inherits settings from the parent level. This loss of inheritance includes any items that are added to or removed from the list at the parent level. If you want to inherit settings from a parent level, revert all of the changes at the child level by using the Revert to Inherited action in the Actions pane.

Move Down

Moves a selected item down in the list. This action is available only when viewing items in the ordered list format.

noteNote
When items in the list are reordered at a child level, the child no longer inherits settings from the parent level. This loss of inheritance includes any items that are added to or removed from the list at the parent level. If you want to inherit settings from a parent level, revert all of the changes at the child level by using the Revert to Inherited action in the Actions pane.

View Unordered List

Displays the list in an unordered format. When you select the unordered list format, you can sort and group items in the list, and perform actions in the Actions pane.

Use the Add Managed Handler and Edit Managed Handler dialog boxes to add new or edit existing managed code handlers on the Web server. 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.

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

 

Element Name Description

Request path

Type a file name extension or file name with an extension for which you want the handler to process requests. For example, if you want the handler to process all requests made for files with the extension .abc, enter *.abc; or if you want the handler to run all requests made for a specific file, type the file name and its extension, such as Myfile.abc.

Type

Type the type name of the managed handler, such as System.Web.Handlers.

When you add a managed handler, make sure that the assembly to which the class belongs is registered in the system.web/compilation section of your Web.config file. Otherwise type the assembly qualified class name of the managed handler. If the class is defined in the App_Code or bin directory you can specify just the class name.

Name

Type a descriptive friendly name for the handler mapping.

Request Restrictions

Opens the Request Restrictions dialog box from which you can specify additional, optional restrictions for the mapping.

Use the Add Script Map and Edit Script Map dialog boxes to add new or edit existing native handlers on the Web server. Native handlers, also known as script engines, are native code .exe or .dll files that respond to specific requests.

noteNote
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 ISAPI extension interfaces.

If you map a type of request to an .exe file (the script engine), CgiModule loads 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 loads the DLL when a request enters the server and it matches the handler mapping. For example, IIS 8 includes a handler mapping for Active Server Pages (ASP). All requests for .asp files are processed by the Asp.dll script engine, which IsapiModule loads because Asp.dll is an ISAPI extension.

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

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.

 

Element Name Description

Request path

Type a file name extension or file name with an extension for which you want the handler to process requests. For example, if you want the handler to run all requests made for ASP files, enter *.asp; or if you want the handler to run all requests made for a specific file, enter the file name and its extension, such as Myfile.asp.

noteNote
If you want to configure a wildcard script map, use the Add Wildcard Script Map action on the Handler Mappings page.

Executable

Type the path to the CGI program or to the ISAPI extension in the physical file system.

noteNote
If you specify the path of a .exe file that has spaces in the path, enclose the path in double quote marks ("). You can also specify command-line parameters with .exe files. These instructions do not apply to .dll files.

Locate the .exe or .dll file in the physical file system.

Name

Type a descriptive name for the handler mapping.

Request Restrictions

Opens the Request Restrictions dialog box from which you can specify additional, optional restrictions for the mapping.

Use the Add Wildcard Script Map and Edit Wildcard Script Map dialog boxes to add or edit a wildcard mapping. The ISAPI extension that you configure for the mapping handles every file name extension, and intercepts every request before the requested page is sent to its mapped handler.

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.

 

Element Name Description

Request path

Displays an asterisk (*).

noteNote
If you want to configure a script map for a specific file name extension or file name with extension, use the Add Script Map action on the Handler Mappings page.

Executable

Type the path of the ISAPI extension in the physical file system.

Locate the .exe or .dll file in the physical file system.

Name

Type a descriptive name for the handler mapping.

Use the Add Module Mapping and Edit Module Mapping dialog boxes to add new or edit existing module mappings on the Web server. You can map a specific file or file name extension to a native module on the Web server, so that when a user requests the file or a file that has the specified extension, the module processes the request. For example, IIS 8 maps all requests for .asp files to IsapiModule, so that module is called when a user requests a file that has the .asp file name extension.

 

Element Name Description

Request path

Type a file name extension or file name with an extension for which you want the handler to process requests. For example, if you want the handler to process all requests made for files with the extension .abc, enter *.abc; or if you want the handler to run all requests made for a specific file, enter the file name and its extension, such as Myfile.abc.

Module

Select the module that you want to process requests for resources specified in the Request path box.

Executable (optional)

Optionally, type a path to the .dll or .exe file when the module you selected in the Module box requires an executable to run, such as the FastCGI module.

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

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

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

Name

Type a descriptive friendly name for the handler mapping.

Request Restrictions

Opens the Request Restrictions dialog box from which you can specify additional, optional restrictions for the mapping.

Use the Request Restrictions dialog box to specify optional restrictions, such as the requested resource type or HTTP verb, for which you want a handler to process requests. Configure restrictions only if you have a specific need to limit the conditions under which a handler processes requests. When you do not configure restrictions, handlers process requests regardless of the resource type requested and the HTTP verbs specified.

 

Element Name Description

Mapping

Configure options on this tab if you want to restrict the handler mapping to requests for specific resource types, such as for a file or a folder. If you do not configure options on this tab, the handler processes requests regardless of the resource type specified in the request.

Invoke handler only if request is mapped to

Select this check box on the Mapping tab if you want the handler mapping to apply only to requests for a specific resource type, such as a request for a file or a folder. If you select this check box, you must also specify the resource type by selecting an option under this check box.

File

Select this option if you want the handler to process requests for a specific file name or file name extension. For example, the ASPClassic handler processes requests for requests made for .asp files. This option is available only if you select the Invoke handler only if request is mapped to check box.

Folder

Select this option if you want the handler to process requests for a folder. Use this restriction if you have a folder with content that you want a specific handler to process. This option is available only if you select the Invoke handler only if request is mapped to check box.

File or folder

Select this option if you want the handler to process requests for files and folders. This option is available only if you select the Invoke handler only if request is mapped to check box.

Verbs

Configure options on this tab if you want to restrict a handler mapping to specific HTTP verbs that clients provide in HTTP headers when they make requests.

All verbs

Select this option if you want the handler to process requests regardless of the verbs that the client specifies. This option is selected by default.

One of the following verbs

Select this option if you want the handler to process requests only when a client provides a specific HTTP verb or specific HTTP verbs in a request. In the corresponding text box, type the HTTP verb or verbs to which you want the handler mapping to apply. For example, type GET if you want the handler to process requests when a client uses the GET verb.

Access

Select one of the options on this tab to configure the access that this handler requires to run in a virtual directory. This setting (together with the feature's access policy that is set on the Edit Feature Permissions dialog box) determines whether a handler can run.

ImportantImportant
Make sure that the required access setting for a handler is correct or else the handler might run unintentionally. For example, if you change the handler's required access from Execute to Read for the ISAPI dll handler, ISAPI extensions will be able to run even if only Read is enabled in the feature's access policy.

Select one of the following options:

  • None: The handler runs even when no access policy options are enabled.

  • Read: The handler will run when Read is enabled in the access policy.

  • Write: The handler will run when Write is enabled in the access policy.

  • Script: The handler will run when Scripts is enabled in the access policy. This selection is the default.

  • Execute: The handler will run when Execute is enabled in the access policy.

Use the Edit Feature Permissions dialog box to configure the access policy that specifies the type of feature rights allowed for handlers at the Web server, site, application, directory, or file levels in IIS. The feature rights that you can enable or disable in the access policy are: read, scripts, and execute. The access policy, together with a handler's required access setting, determines whether a handler can run. If a handler requires a type of feature right that is not enabled in the access policy, the handler is disabled and all requests that are processed by the handler (based on the handler mapping) fail, unless there is another handler that can process the request.

When you select an option in the Edit Feature Permissions dialog box, the State column on the Handler Mappings page displays Enabled for the handlers that the selection enables. Similarly, when you clear a selection in the Edit Feature Permissions dialog box, the State column on the Handler Mappings page displays Disabled for the handlers that the selection enables. You can preview the handlers that are enabled or disabled by viewing the Handler Mappings page, and then clicking OK to dismiss the Edit Feature Permissions dialog box. If you click Cancel instead of OK, the changes that you make in the dialog box will not be saved.

noteNote
To configure the required access setting for a handler, you can edit the handler mapping and click Request Restrictions to configure the setting on the Access tab.

For example, you might enable Read and Scripts at the web server level, but decide to disable Scripts for a specific site that serves only static content. This setting prevents the server from running scripts for that site if a user adds a handler mapping for a script or executable at the site level.

 

Element Name Description

Read

Select the Read check box to enable handlers that require read access to a virtual directory or clear the Read check box to disable handlers that require read access to a virtual directory. If you want to serve static content, or want to configure default documents and directory browsing, enable read in an access policy. By default, read permissions are enabled.

Scripts

Select the Scripts check box to enable handlers that require script rights to a virtual directory or clear the Scripts check box to disable handlers that require script rights in a virtual directory.

Execute

Select the Execute check box to enable handlers that require execute rights in a virtual directory or clear the Execute check box to disable handlers that require execute rights in a virtual directory. The Execute check box is enabled only when the Scripts check box is selected. If you want to enable executable files, such as .exe, .dll, and .com files, to run in addition to scripts, enable execute in an access policy only.

ImportantImportant
For security and performance reasons, enable executable rights only for programs that you have tested and that your applications require.

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.