IIS URL Rewrite Example

I recenlty played around with the URL rewrite module in IIS, and would like to tell you what I have learnt.

URL rewrite is happening on server side and any parameters after ‘#’ will not be passed to server. For references, you can learn from the following links. I will explain how to define rewrites using regular expressions (regex).


For URL rewrite rules, there are few parameters you can define:

  1. URL; this is the original URL without hash value. You can define to match a regex and use matched values by {R:N} in new URL, where N is between 0 and 9.
  2. Conditions; You can define to match all or any of the conditions. When define a condition, it is similar to rules. You need to define the input and pattern fields; which inputs needed to match the regex defined in pattern field. You can also use matched values in new URL by {C:N} where N is between 0 and 9. By default, only the last condition can be referenced. If you want to reference all matched value in conditions, you need to select the checkbox “Track capture groups across conditions” under condition list. For input, you can use {R:N} or server variable like {REQUEST_URI}/{QUERY_STRING}; and you can also apply a rewrite mapping to lookup a new value. For example, I can define a rewrite mapping named “NewSiteRewrites” and uses it to map URL ({R:0}); the input will be {NewSiteRewrites:{R:0}}.

Rewrite Rule Definition screen capture

Let’s say the original URLs are http://yourdomain.com/redmond/events?start=10/01/2014&end=11/01/2014. The expected redirect is http://newdomain.com/washington/redmond?start=10/01/2014&end=11/01/2014#events.  Also original URL query string and new URL hash are optional; and it can be HTTP or HTTPS.  Another valid original URL can be https://yourdomain.com/redmond/details, redirected to https://newdomain.com/washington/redmond

Before start defining the rule and mapping, I would like to show the value of each variable for the original URL:

  1. {REQUEST_URI} = /redmond/events?start=10/01/2014&end=11/01/2014
  2. {QUERY_STRING} = start=10/01/2014&end=11/01/2014; Note: “?” is not included.
  3. {HTTPS} = off; this is a server variable to identify whether http or https is used.  Possible values are “on” and “off”.  You can also use {SERVER_PORT_SECURE}, which returns 0 or 1.
  4. Requested URL under “Match URL” section = redmond/events; Note: “/” is not included at the beginning.

Back to our example:

  1. I break down the new URL into parts: “http”, “://newdomain.com/”, “redmond/events”, <query string>, and <hash>.
  2. “http” part; I create a mapping “CheckSSL” and return either “http” or “https” and directly used in Redirect URL field.
  3. “://newdomain.com”, hard-coded value in Redirect URL field.
  4. “redmond/events” and <hash>, I create a mapping “MyRerouteMapping”, e.g. “/redmond/events” is mapped to “/redmond#events”; and define a condition pattern to parse the path and hash; which will be used in Redirect URL field.
  5. <query string>, I cannot use {QUERY_STRING} directly as it doesn’t have “?” at the beginning; and <query string> is optional.  Also we cannot use the checkbox “Append query string” as hash may exist. Therefore I define a condition pattern to parse from {REQUEST_URI}.

For the complete definitions, please refer to below web.config.

If your rewrite is very complicated, you can also define your only rewrite provider and call it like rewrite mapping.  For more details, please refer to http://www.iis.net/learn/extensions/url-rewrite-module/developing-a-custom-rewrite-provider-for-url-rewrite-module.

<?xml version="1.0" encoding="UTF-8"?>
				<rule name="RouteToWWW" patternSyntax="ECMAScript" stopProcessing="true">
				  <match url=".*" />
				  <conditions logicalGrouping="MatchAll" trackAllCaptures="true">
					<add input="{MyRerouteMap:{R:0}}" pattern="([^#]*)(#.*)?" />
					<add input="{REQUEST_URI}" pattern="[^\?]*(\?.*)?" />
				  <action type="Redirect" url="{CheckSSL:{HTTPS}}://www.microsoft2.com/{C:1}{C:3}{C:2}" appendQueryString="false" />
                <rewriteMap name="CheckSSL">
                    <add key="on" value="https" />
                    <add key="off" value="http" />
                <rewriteMap name="MyRerouteMap">
                    <add key="redmond/events" value="redmond#events" />
                    <add key="redmond/details" value="redmond" />

Happy URL rewrites!!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s