Handler Mappings
Applies To: Windows Server 2012 R2, Windows Server 2012
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
UI Elements for Handler Mappings
The following tables describe the UI elements that are available on the feature page and in the Actions pane.
Feature Page Elements
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:
|
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. |
Actions Pane Elements
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.
|
||
Lock |
Locks the selected handler mapping so it cannot be overridden at lower levels in configuration. Note 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. Note 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. Note 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. Note 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. |
.jpeg)
NoteAdd or Edit Managed Handler Dialog Box
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.
Note
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. |
Add or Edit Script Map Dialog Box
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.
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 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.
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.
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.
|
||
Executable |
Type the path to the CGI program or to the ISAPI extension in the physical file system. Note 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. |
Add or Edit Wildcard Script Map Dialog Box
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 (*).
|
||
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. |
Add or Edit Module Mapping Dialog Box
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.
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. Note 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. |
Request Restrictions Dialog Box
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.
Select one of the following options:
|
.jpeg)
ImportantEdit Feature Permissions Dialog Box
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.
Note
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.
|