Using URL Rewrite Module

Introduction

The Microsoft URL Rewrite Module for IIS 7.0 provides flexible rules-based rewrite engine that can be used to perform broad spectrum of URL manipulation tasks, including, but not limited to:

• Enabling user friendly and search engine friendly URL with dynamic web applications;
• Rewriting URL’s based on HTTP headers and server variables;
• Web site content handling;
• Controlling access to web site content.

Features

The Microsoft URL rewrite module includes these key features:

• Rules-based URL rewriting engine. Rewrite rules are used to express the logic of what to compare/match the request URL with and what to do if comparison was successful. Web server and site administrators can use rewrite rule sets to define URL rewriting logic.

• Regular expression pattern matching. Rewrite rules can use ECMA-262 compatible regular expression syntax for pattern matching.
  Wildcard pattern matching. Rewrite rules can use Wildcard syntax for pattern matching

• Wildcard pattern matching. Rewrite rules can use Wildcard syntax for pattern matching

• Global and distributed rewrite rules. Global rules are used to define server-wide URL rewriting logic. These rules are defined within applicationHost.config file and they cannot be overridden or disabled on any lower configuration levels. Distributed rules are used to define URL rewriting logic specific to a particular configuration scope. This type of rules can be defined on any configuration level by using web.config files.

• Access to server variables and http headers. Server variables and HTTP headers provide additional information about current HTTP request. This information can be used to make rewriting decisions or to compose the output URL.

• Various rule actions. Instead of rewriting a URL, a rule may perform other actions, such as issue an HTTP redirect, abort the request, or send a custom status code to HTTP client.

• Rewrite maps. Rewrite map is an arbitrary collection of name-value pairs that can be used within rewrite rules to generate the substitution URL during rewriting. Rewrite maps are particularly useful when you have a large set of rewrite rules, all of which use static strings (i.e. there is no pattern matching used). In those cases, instead of defining a large set of simple rewrite rules, you can put all the mappings between input URL and substitution URL as keys and values into the rewrite map, and then have one rewrite rule which references this rewrite map to look up substitution URL based on the input URL.

• UI for managing rewrite rules. Rewrite rules can be added, removed and edited by using "URL Rewrite Module" feature in IIS Manager.

• GUI tool for importing of mod_rewrite rules. URL rewrite module includes a GUI tool for converting rewrite rules from mod_rewrite format into an IIS format.  

Where to get the module

Download the x86 CTP version for IIS 7.0: http://www.iis.net/downloads/default.aspx?tabid=34&g=6&i=1691

Download the x64 CTP version for IIS 7.0: http://www.iis.net/downloads/default.aspx?tabid=34&g=6&i=1692

Using the module

These articles cover the functionality of the URL Rewrite Module and explain how to use it to accomplish common URL rewriting scenarios.

Learning the basics

• Creating rewrite rules
• Using Failed Request Tracing to trace rewrite rules
• Using global and distributed rules
• Using rewrite maps
• Importing rewrite rules
• Enabling "Pretty Permalinks" in WordPress

Functionality reference

• URL Rewrite Module configuration schema reference

In This Section

Comments

1. Submitted on Jun 12 2008 by
   geekinabox I'm curious if you'll implement functionality to 'redirect POSTs' , too? I've see plenty of instances where folks want to 'redirect' all traffic to a site, be it a GET or a POST. GETs work fine w/ a standard redirect (the querystring is easily appended to the new Location), but POSTs do not. That is, if a POST is redirected, the browser does not re-POST to the new location; instead it issues a GET to the new Location, but the body of the POST data is lost. The loss of the data can -- in certain instances -- be problematic. The solution to redirecting a POST is pretty simple ... instead of issuing a HTTP redirect, send back a hidden HTML form to the browser with all of the name/value POST data as hidden fields, and, via client side scripting (onLoad) have the form auto-submit a new POST to the new 'redirected' URL. This isn't a true redirect, but serves the same end folks often want. Bottom-line: I think it would be valuable to bake this POST psuedo-redirect functionality into the rewrite module. Perhaps when a user selects to do a redirect, there could be a checkbox to 'Also perform scripted redirect for POSTs' (or something better worded) which would enable this behavior.
2. Submitted on Jun 17 2008 by
   Leshchinsky Что же ты делаешь с нами великий и могучий ... IIS 7 ? http://dev.net.ua/blogs/leshchinsky/archive/2008/06/17/6339.aspx
3. Submitted on Jun 24 2008 by
   lonevvolf It's great that Microsoft is providing an official module for this - there's just one very important thing missing for me: There's no way to extend it, for example, to read/write the customer's cookies. I would like to change the URL depending on a cookie from the customer, as well as update their cookie in certain cases. Is there anything planned for this?
4. Submitted on Jun 24 2008 by
   lonevvolf Hmmm, well, reading cookies seems to work using {HTTP_COOKIE}, but I don't think writing to the response will work. In any case, I can't yet seem to select a single cookie value with a regular expression. :S
5. Submitted on Jul 01 2008 by
   ruslany Lonevvolf, you are right about how to read a cookie. The cookie can be accessed by using {HTTP_COOKIE} as an input in rule's condition. If you cannot get the regex pattern to match the cookie value, as a first step I would recommend to enable failed request tracing (http://learn.iis.net/page.aspx/467/using-failed-request-tracing-to-trace-rewrite-rules/) and then see what the {HTTP_COOKIE} value actually contains. That way you will have a better idea about how the cookie string looks like and may be able to adjust your regex accordingly. There is no functionality in URL rewrite module to set the cookie for the response.
6. Submitted on Jul 18 2008 by
   riggit Hi. Can the IIS7 URL rewriter be used with Cassini server? I imagine not, but I wonder how to incorporate this useful feature into the development process. The Intelligencia offering allows development with Cassini and then deployment to a web server. It would be great to use the new IIS7 version instead. Thanks!
7. Submitted on Jul 18 2008 by
   mwoj Ruslany, when I try to install the URL Rewrite Module on my Windows Vista SP1 (with IIS 7.0) PC for testing, I get the following error: IIS Version 7.0 or greater is required to install Microsoft URL Rewrite Module for IIS 7.0. Any ideas how to get around this problem? Thanks.
8. Submitted on Jul 21 2008 by
   ruslany Possible way to workaround the error reported by mwoj is to run the installer from the command line: msiexec /I rewrite_x86_TP1.msi