Using Back References

Updated: November 6, 2009

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

Parts of the input of rules or conditions can be captured in back references. The back references can be then used within rule actions to construct substitution URLs or within rule conditions to construct input strings.

Back references are generated in different ways, depending on which kind of pattern syntax is used for the rule. When ECMAScript pattern syntax is used, a back reference can be created by putting parentheses around the part of the pattern that must capture the back reference. For example, if the URL "07/article.html" is requested, the pattern ([0-9]+)/([a-z]+)\.html will put "07" and "article" in back references. If wildcard pattern syntax is used, back references are always created whenever an asterisk symbol (*) is used in the pattern. For example, if the requested URL is "contoso/test.html" and the pattern is */*.html, "contoso" and "test" will be captured in back references. However, no back references are created when "?" is used.

Usage of back references is the same regardless of which pattern syntax was used to capture them. Back references can be used in the following locations within rewrite rules.

  • In the condition input string.

  • In rule substitution strings, specifically in the URL attribute of the Rewrite and Redirect actions, and in the statusLine and responseLine of the CustomResponse action.

  • In the key parameter to the rewrite map.

Back references to condition patterns are identified by {C:n}, where n is a number from 0 to 9. Back references to rule patterns are identified by {R:n}, where n is a number from 0 to 9. Note that for both condition and rule back references, {R:0} and {C:0} will contain the matched string. For example, if you have the string "," and the pattern ^(www\.)(.*)$, the back references will be indexed as follows.

{C:0} will contain "".

{C:1} will contain "www.".

{C:2} will contain "".

Within a rule action, you can use the back references to the rule pattern and to the last matched condition of the rule. Within a condition input string, you can use the back references to the rule pattern and to the previously matched condition.

The following rule example demonstrates how back references are created and referenced.

<rule name="Rewrite subdomain">
<match url="^(.+)" > <!-- rule back reference is captured here -->
<add input="{HTTP_HOST}" type="Pattern" pattern="^([^.]+)\.mysite\.com$"> <!-- condition back reference is captured here -->
<action type="Rewrite" url="{C:1}/{R:1}" /> <!-- rewrite action uses back references to condition and to rule when rewriting the url -->

See Also

Community Additions