Configure Request Restrictions for a Handler Mapping (IIS 7)

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

Configure optional restrictions for handler mappings when you want a handler to respond only to requests for specific resource types, such as to a file or folder, or to requests for specific verbs. You can also specify the type of access that a handler requires to run in a virtual directory. A handler's required access setting together with the Handler Mapping feature's access policy determines whether a handler can run. For more information about the Handler Mapping feature's access policy, see Edit Feature Permissions for the Handler Mappings Feature (IIS 7).

Note

You should configure options in the Request Restrictions dialog box only if you have a specific requirement to limit the conditions under which a handler processes requests. If you do not configure restrictions, handlers will process requests regardless of the resource type requested and the HTTP verbs specified.

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 configure request restrictions for a 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, right-click a handler mapping to which you want to add request restrictions and then click Edit.

  4. In the Request Restrictions dialog box, on the Mapping tab, select Invoke handler only if request is mapped to if you want the handler to respond to requests only for a specific resource type. Then select one of the following options:

    • File, if you want the handler to respond only when the target resource requested is for a file.

    • Folder, if you want the handler to respond only when the target resource requested is a folder.

    • File or Folder, if you want the handler to respond only when the target resource requested is either a file or a folder.

  5. In the Request Restrictions dialog box, on the Verbs tab, select one of the following options:

    • All verbs, if you want the handler to respond to requests regardless of the verbs sent in the request.

    • One of the following verbs, if you want the handler to respond to requests that include a specific verb or verbs. Then type the verb or verbs in the corresponding box.

  6. In the Request Restrictions dialog box, on the Access tab, select one of the following options:

    • None, if you want the handler to run even when no access policy options are enabled.

    • Read, if you want the handler to run when Read is enabled in the access policy.

    • Write, if you want the handler to run when Write is enabled in the access policy.

    • Script, if you want the handler to run when Scripts is enabled in the access policy. This is the default option.

    • Execute, if you want the handler to run when Execute is enabled in the access policy.

Important

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

  1. Click OK.

Command Line

To configure request restrictions for a handler mapping, use the following syntax:

**appcmd set config /section:handlers /[name='string'].attribute:**string

The variable name string is the name of the handler mapping that you want to change. The variable attribute is the attribute that you want to change or add to the handler mapping, and attribute string is the value that you want to set for the attribute.

For example, to specify that a handler named ImageCopyrightHandler requires Execute rights in order to run, type the following at the command prompt, and then press ENTER:

appcmd set config /section:handlers /[name='ImageCopyrightHandler'].requireAccess:Execute

Important

When you configure the requireAccess attribute for a handler mapping, make sure that the setting is correct or else the handler may run unintentionally. For example, if you change the required access from Execute to Read for ISAPI-dll handler in a configuration file, ISAPI extensions will be able to run for sites or applications that use that configuration file, even if only Read is enabled in the access policy. For more information about the requireAccess attribute, and how the requireAccess attribute relates to the accessPolicy attribute in the <handlers> section to enable or disable handlers, see Edit Feature Permissions for the Handler Mappings Feature (IIS 7).

If you want to add a value to an attribute that is already configured for a handler mapping, you must specify all the values that you want for that attribute when you change the handler mapping. For example, to specify that the handler from the previous example, ImageCopyrightHandler, respond only to requests for HTTP verbs GET and HEAD, type the following at the command prompt, and then press ENTER:

appcmd set config /section:handlers /[name='ImageCopyrightHandler'].verb:GET,HEAD

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:

  • HandlerAction class (IIS)

  • HttpHandlerAction 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 Edit Feature Permissions for the Handler Mappings Feature (IIS 7) Add a Managed Handler Mapping (IIS 7) Add a Script Map Handler Mapping (IIS 7) Add a Module Handler Mapping (IIS 7)