Creating Rewrite Maps

Updated: November 6, 2009

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

A rewrite map is a collection of name-value pairs that you can use to generate substitution URLs in rewrite rules. Rewrite maps are useful when you have a large set of rewrite rules that use static strings without any pattern matching. In these cases, instead of defining a large set of simple rewrite rules, you can put all the mappings into a rewrite map, as keys and values, between the input URL and the substitution URL. Then, to look up the substitution URL that is based on the input URL, you will have one rewrite rule that references the rewrite map.

The following example shows how a rewrite map consists of static remappings.


<rewriteMap name="MyRewriteMap">
  <add key="a.html" value="b.html" />
  <add key="c.aspx" value="d.aspx" />
  <add key="e.php" value="f.php" />
</rewriteMap>

You can have any number of rewrite maps on any configuration level except the file level. Rewrite maps are located within a <rewriteMaps> collection element. Rewrite maps are referenced by using the following syntax.

{RewriteMapName:Key}

The Key parameter is a string that can include back references to the rule or rule condition. For example, the following are valid rewrite maps.


{MyRewriteMap:contoso/{R:1}/fabrikam/{C:1}}

{MyRewriteMap:a.html}

{MyRewriteMap:{R:1}?{C:1}&contoso=fabrikam}

When you supply a key parameter within a rewrite map reference, the URL Rewrite module looks up the corresponding value and substitutes it. If a key lookup fails, then the key itself will be used as the substitution string.

You can use the rewrite map feature within rewrite rules in the following locations.

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

The following example rewrite map 1) and example rewrite rule 2) give the result 3) indicated in the table.

1) The rewrite map.


<rewrite>
 <rewriteMaps>
  <rewriteMap name="StaticRewrites">
    <add key="diagnostics" value="defaultspx?tabid=2&amp;subtabid=29" />
    <add key="webcasts" value="default.aspx?tabid=2&amp;subtabid=24" />
    <add key="php" value="default.aspx?tabid=7116" />
  </rewriteMap>
 </rewriteMaps>
</rewrite>


2) The rewrite rule.

<rewrite>
 <rule patternSyntax="Wildcard">
  <match url="*" />
  <action type="Rewrite" url="{StaticRewrites:{R:1}}"/>
 </rule>
</rewrite>

3) The result.

 

Requested URL Rewritten URL

/diagnostic

default.aspx?tabid=2&subtabid=29

/webcasts

default.aspx?tabid=2&subtabid=24

/php

default.aspx?tabid=7116

/default.aspx

/default.aspx

noteNote
The requested URL /default.aspx remains as /default.aspx. Because the rewrite map does not contain an element that contains key="default.aspx", the requested URL is passed on verbatim as the "rewritten" URL.

See Also

Community Additions

ADD
Show: