URLRewrite and IIS: Part Two – Introduction to “rewrite”

This is the second in our series about URLRewrite. We are going to focus on another aspect of URLRewrite. Namely the concept of rewriting a url “in-flight” to allow a URLRewrite rule to conduct an action that the administrator wishes to implement on the IIS server.

The subject of rewrites versus redirects immediately comes to mind. As I have worked over the years with IIS and URLRewrite, I found it far easier to use redirect rules, but these come with a penalty, since an incoming request causes additional overhead in the form of a new HTTP request being sent the server. Ideally, if you can avoid this, you should use a Rewrite rule to change the incoming request on the fly rather than overt redirect. The rewrite rule we are going to show you is a “redirect in disguise” and accomplishes the task of a redirect on one succinct operation rather than two.

Lets design the use-case:

Imagine we have a directory on a web site and this directory is no longer used, but you want to inform your users that the directory has been retired. What to do?

In a standard redirect rule, you would match on a particular directory and then redirect to the retired page as follows (Note, we are going to use “/docs” as the example directory that is no longer valid):

Conditionals for redirect rule


Action for redirect rule.

The code that is placed into the web root “web.config” file looks like this:

<rule name=”Example Redirect” patternSyntax=”ECMAScript” stopProcessing=”true”>
<match url=”(.*)” />
<action type=”Redirect” url=”/retired.html” />
<conditions logicalGrouping=”MatchAny”>
<add input=”{PATH_INFO}” pattern=”^/docs/(.*)” />
<add input=”{PATH_INFO}” pattern=”/docs” />

When run in the browser, the following occurs:

Result of redirect run. Note that the URL changed to point to the “retired.html” page.


The rule fires and redirects to the expected url and is shown in the browser.

Note that in this rule, there are two conditions, either of which, when run, will perform the redirect. The first is to match any and all sub-directories of “docs”, while the second rule handles the case where the url of “http:/someserver/docs” is handled as a specific case of it’s own. I am absolutely certain some of you will comment on there being better ways to do this in this example, but for purposes of clarity, this is the format I chose to use. If you do want to send in examples of better ways to do this, visit the “contact” link and I will share your comments and ideas in future articles. Remember, I’m learning everyday too and there is ALWAYS a better way to do things ;>)

So… Our redirect example above is really pretty good. It handles the full range of references to references to the “/docs” directory and sub-directories. But is there a better way to do it? Let’s try the “rewrite” option and see what happens (after first disabling the prior example!):

Conditional at the URL section

Action clause for the rewrite rule.

The code that is placed into the web root “web.config” file looks like this:

<rule name=”Example Rewrite” stopProcessing=”true”>
<match url=”^docs/(.*)$” />
<action type=”Rewrite” url=”/retired.html” />

Now let’s execute this rule:

The page loads the same “retired.html” as before, but the URL remains the same on the browser URL bar!


This is a three for one benefit. The browser doesn’t have to incur local overhead on a redirect. The server doesn’t have to work harder and the apparent URL doesn’t change on the client end. It is all handled at the server end of things.

Isn’t this a little more efficient? It does everything needed in four lines and with a single transaction. In truth, the redirect rule could have been more efficient, but again, for purposes of clarity, we want to get you to think in new ways about URLRewrite and to, as the character “Morpheous” says in “The Matrix” says, “free your mind”. A hint is to look at the line “<match url=”^docs/(.*)$” />” and perhaps try your own experiments with the redirect. That is the other thing with URLRewrite and, for that matter, mod_rewrite in Apache webservers. You want to try new rules, new ideas and play with them to get a good feel for what works and what does not. Experiment and don’t be afraid to fail.

Back to the rewrite rule. It is efficient and small. The minor penalty for the in-flight rewrite is less than what would be incurred against a redirect rule and provides a first taste of what can be done.

In truth, this is a small taste of the many things the rewrite rules can be used for. We will be covering more rewrite examples in coming articles and also discussing back-references and URLRewrite. These are extremely powerful and useful for helping to construct new urls and are a staple tool you will need to learn to effectively use URLRewrite.

Until next time!