Condividi tramite

Configuring Inbound Rewrite Rules

  • Articolo

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

Inbound rules are used to modify HTTP request URLs. These rules can serve several purposes, such as presenting a more user-friendly URL namespace for your Web site, redirecting requests for URLs to new locations, or preventing access to URLs.

Inbound Rewrite Rules Overview

Inbound rewrite rules define the syntax for rewriting HTTP request URLs based on a set of parameters that you specify. Conceptually, an inbound rewrite rule consists of the following parts:

  • Pattern: The pattern specifies either a wildcard pattern or a regular expression that will be used to match URLs for a rule. For example, “*.asp” or “^example/?$”.

  • Conditions: Conditions are optional, and may be used to specify additional logical comparisons if a URL matched the rule pattern. By using conditions, rewrite rules can test the values of HTTP headers or server variables, or verify that the requested URL corresponds to a file or directory on a physical file system.

  • Action: The action specifies the behavior for the rewrite rule if the pattern and conditions are met for the rule.

Inbound Rewrite Rules Scope

Inbound rewrite rules can be defined in two different collections, each of which is configured at a different hierarchical level:

  • <globalRules>

    Rules in this collection can be defined only on the server level, and are used to define server-wide URL rewriting logic. These rules are defined within the ApplicationHost.config file, and they cannot be overridden or disabled on any lower configuration levels. Global rules always operate on absolute URLs; that is, the requested URI without the server name. Global inbound rules are evaluated early in the IIS pipeline, during the PreBeginRequest event.

  • <rules>

    Rules in this collection define the URL rewriting logic that is specific to a particular configuration scope. These rules are called distributed rules because they can be defined at the server, site, application, or URL level. These rules can be added on any configuration level by using Web.config files or by using <location> tag within the ApplicationHost.config file or Web.config files. Distributed rules are evaluated during the BeginRequest event of the IIS pipeline.

Inbound Rules Execution

Each hierarchical level in IIS can have any number of rewrite rules defined, and rules are evaluated in the order that they are specified in the IIS configuration files. The URL rewrite module processes through the collection of rules by using the following algorithm:

  • First, the URL is matched against the pattern of a rule. If the pattern does not match, the URL Rewrite module moves on to the next rule.

  • If the pattern matches for a rule, the URL Rewrite module tests for conditions:

    • If there are no conditions for the rule, the URL Rewrite module will perform the action for this rule.

    • If there are conditions for the rule, the URL Rewrite module will evaluate the conditions. If the conditions are met for the rule, then the action for the rule will be performed.

    • Any rule may have the StopProcessing flag defined:

      • If the StopProcessing flag is turned on, subsequent rules will not be processed and the rewritten URL that is produced will be passed to the IIS request pipeline.

      • If the StopProcessing flag is turned off, the URL Rewrite module will move on to the next rule and will use the rewritten URL as an input for the next rule.

Note

By default, the StopProcessing flag is turned off.

If inbound rewrite rules are defined on multiple configuration levels, the URL Rewrite module evaluates the rules in the following order:

  • Evaluate all global rules.

  • Evaluate a rule set that includes distributed rules from parent configuration levels in addition to rules from current configuration level. The evaluation is performed in a parent-to-child order, which means that parent rules are evaluated first and the rules that are defined on a last child level are evaluated last.

Original URL Preservation

The URL Rewrite module preserves the original requested URL path in the following server variables:

Server Variable Description

HTTP_X_ORIGINAL_URL

Contains the original URL in decoded format.

UNENCODED_URL

Contains the original URL exactly as it was requested by the Web client, with all original encoding preserved.

Types of Inbound Rules

There are several types of inbound rules that can be created:

User-friendly URL namespaces

Web applications often specify application parameters along the URL, for example:

https://www.contoso.com/page.aspx?A=123\&B=456\&C=789

This method of specifying application parameters creates URLs that are difficult to copy or understand and often such URL namespaces are not indexed by search engines. By using rewrite rules, you can create a URL namespace that is easier to understand and index. Following the earlier example, you could create a URL namespace that resembles the following:

https://www.contoso.com/123/456/789/

You can create user-friendly URL namespaces by using the User friendly URL template in the Add Rule(s) Dialog Box. For more information about how to create user-friendly URL namespace, see Add rules to enable user friendly URLs Dialog.

Rewrite Maps

Rewrite maps let you create collections of name and value pairs that will be used for rewriting. As an example, instead of using an algorithmically-created rule using regular expressions or wildcard characters, you can create a series of static mappings.

For more information about how to use rewrite maps, see Add rule with rewrite map Dialog and Using Rewrite Maps in the URL Rewrite Module.

Request Blocking

Request blocking rules let you deny access to content based on a variety of criteria, such as the URL path, user-agent header, IP address, query string, HTTP referrer, or host header. Requests will be blocked based on regular expressions or wildcard characters, and can block requests using one of several HTTP responses, such as 401 Access Denied, 403 Access Forbidden, or 404 Not Found. You can also create a custom HTTP response that returns any desired HTTP status/substatus combination.

For more information about how to create request blocking rules, see the Add request blocking rule Dialog topic.

See Also

Concepts

Edit Inbound Rule Page