Manage Static Rewrite Rules with RewriteMaps (IIS)

RewriteMaps allow you to centrally manage any number of redirects and rewrite rules in an easy and organized manner. They are simple one-to-one, old-to-new relationships that do not use regular expressions or wildcard matching.

Situations where RewriteMaps can prove particularly useful is when a website introduces a new, or changes its current, CMS or web application. In these cases, dynamic rules via regular expressions may be less useful than simple, static, one-to-one mappings of old to new URLs. For SEO purposes, any redirects you create to address this type of scenario should be Permanent (301).

Saving RewriteMaps outside of the main web.config is easiest, following a similar technique described for saving rewrite rules in an external file. They can be stored in web.config as well, but RewriteMaps generally grow to be quite large and contain a large number of entries, and to keep web.config from getting bloated it’s best to store them in a dedicated file.

A RewriteMap has the following structure, providing a one-to-one mapping of old to new URLs:

<rewriteMaps>
	<rewriteMap name="Redirects">
		<add key="/old_url" value="/new_url" />
		<add key="/another_old_url" value="/another_new_url" />
	</rewriteMap>
</rewriteMaps>

We’ll plan on keeping our various RewriteMaps in the non-ironically named rewritemaps.config. We include a reference to it in web.config as shown below:

<system.webServer>
	<rewrite>
	    <rewriteMaps configSource="rewritemaps.config" />
	</rewrite>
</system.webServer>

The rewritemaps.config file then contains your various RewriteMaps. It does not require the XML schema declaration and starts directly at the <rewriteMaps> node:

<rewriteMaps>

	<rewriteMap name="Redirects">
		<add key="/blog/" value="/articles/" />
		<add key="/aboutus.html" value="/info/about-us" />
	</rewriteMap>

	<rewriteMap name="Rewrites">
		<add key="/robots.txt" value="/robots.php" />
	</rewriteMap>

</rewriteMaps>

In the above rewritemaps.config file, we’re organizing our redirects and rewrites into separate maps. Once this file is created, we can leverage them as shown below (if you have your rewrite rules stored in an external file, these would go there, otherwise in web.config’s <rules> section):

<rule name="Apply redirects from rewritemaps.config">
	<match url=".*" />
	<conditions>
		<add input="{Redirects:{REQUEST_URI}}" pattern="(.+)" />
	</conditions>
	<action type="Redirect" url="{C:1}" redirectType="Permanent" appendQueryString="true" />
</rule>

<rule name="Apply rewrites from rewritemaps.config">
	<match url=".*" />
	<conditions>
		<add input="{Rewrites:{REQUEST_URI}}" pattern="(.+)" />
	</conditions>
	<action type="Rewrite" url="{C:1}" />
</rule>

The above rules will examine the request URI and see if there any mapping entries which match. If found in any of the RewriteMaps, the request will be redirected or rewritten per the map entry.

Because the URL mappings defined in a RewriteMap are ultimately executed as <rule>’s, you control when they are evaluated (before or after other, dynamic rules) by moving these rules higher or lower in the <rules> block, thereby increasing or decreasing their execution priority.