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 based on URL segments or request metadata.

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

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

• Support for IIS kernel mode and user mode output caching. IIS 7.0 output caching provides significant performance improvements for web applications. URL rewrite module is fully compatible with both types of output caching. This means that it is possible to safely cache responses for rewritten URL's and thus boost the performance of web applications that rely on URL rewriting.

• String manipulation functions. Built-in string manipulation functions can be used to convert URLs to lowercase and to perform URL encoding and decoding.

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

• Failed Request Tracing support. IIS7.0 Failed Request Tracing can be used to troubleshoot errors related to URL rewriting.

• Rule templates. Rule template is an extension for URL rewrite module user interface, that simplifies creation of rewrite rules for a particular task.  The module includes 3 built-in rule templates, plus it allows plugging in any number of custom templates.

• UI for testing of regular expression and wildcard patterns. A GUI tool for testing rule patterns is included into the module's user interface. The tool can be used to quickly check how the regular expression or wildcard pattern works. Also, it can be used for troubleshooting and debugging of problems related to pattern matching.

• UI for managing rewrite rules and rewrite maps. Rewrite rules and rewrite maps 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 version for IIS 7.0

Download the x64 version for IIS 7.0

Upgrading from Go Live release

If you already have Go Live release of URL rewrite module installed then the installation package will upgrade it to RTW release. All rewrite rules in applicationHost.config and web.config files will be preserved.

ASP.NET update

The URL rewrite module installer package includes an ASP.NET update that fixes ASP.NET bugs specific to URL rewriting. In particular, the update contains fixes for the following bugs:

1. ~ operator in ASP.NET Web server control is resolved incorrectly when using URL rewriting
2. ASP.NET SiteMap.CurrentNode property returns null when sitemap contains virtual URLs

The update is applied only if the machine where URL Rewrite module is being installed has .NET Framework version 3.5 SP1 or higher. If required version of .NET Framework is installed after URL Rewrite module has been installed, then the ASP.NET update can be applied by re-running URL Rewrite module installer in repair mode.

For more details about these and other ASP.NET issues related to URL rewriting refer to this article.

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
• Rule templates
  • User Friendly URL
  • Rule with Rewrite Map
  • Request Blocking
• Testing rule and condition patterns

References and guidance

• URL Rewrite Module configuration reference
• URL Rewriting and ASP.NET routing
• URL Rewriting and Request Filtering
• URL Rewriting for ASP.NET Web Forms
• Developing rule templates for URL Rewrite module

Video walkthrough

• Using URL rewrite module - video walkthrough

Changes since Go Live release

The following additions, changes and important bug fixes have been made to URL rewrite module since Go Live release:

1. Added string manipulation functions UrlEncode and UrlDecode.
2. Provided access to a raw original URL via server variable UNENCODED_URL. This server variable now contains the raw encoded URL exactly as it was requested by web browser.
3. Added UI for configuring rewrite rules for Application Request Routing.
4. Added support for in-place upgrade from Go Live release of URL rewrite module.
5. Added functionality to clean up the internal cache to avoid excessive usage of memory when caching rewrite rules.
6. Fixed a bug related to rewriting of URLs that contain non-ASCII characters.
7. Fixed a bug in regular expression engine that caused character ranges to be evaluated incorrectly for case insensitive patterns.
8. Included an update for IIS FastCGI module into the installer package.
9. Included an update for System.Web.dll into the installer package.
10. Included an update for IIS SetUri function into the installer package.

Known Issues

1. mod_rewrite rules that use REQUEST_URI server variables may not work correctly when imported by using URL Rewrite “Import Rules…” feature. To fix the imported rules use any text editor to open the web.config file that contains those rules. Locate the <rewrite> section and then within that section replace all instances of string “{SCRIPT_NAME}” with the string “{URL}”. 
2. Digest authentication cannot be used with URL rewrite module.
3. ASP.NET Forms Authentication uses rewritten URL for redirection. For example, if requested URL is "/article.htm" and URL rewrite module rewrites the URL to "/article.aspx", which is protected by Forms Authentication, then ASP.NET will redirect to "/login.aspx?ReturnUrl=%2Farticle.aspx".
4. Auto-detect mode in ASP.NET Forms Authentication uses rewritten URL for redirection. For example, if requested URL is "/article.htm" and URL rewrite module rewrites the URL to "/article.aspx", which is protected by Forms Authentication, then ASP.NET will redirect to "/article.aspx?AspxAutoDetectCookieSupport=1".
5. UseUri mode in ASP.NET Forms Authentication uses rewritten URL for redirection. For example, if requested URL is "/article.htm" and URL rewrite module rewrites the URL to "/article.aspx", which is protected by Forms Authentication, then ASP.NET will redirect to "/(S(vy2ebt45imfkmjjwboow3l55 ))/article.aspx".
6. ASP.NET rewrites back to the original URL when using URI-based authentication or cookie-less session state. For example, when request is made to "/(S(vy2ebt45imfkmjjwboow3l55 ))/article.htm" and URL rewrite module rewrites "/article.htm" to "/article.aspx", then ASP.NET will rewrite the URL back to "/article.htm", which may result in a "404 - File Not Found" error.
7. IIS DefaultDocument module may redirect to rewritten URL when URL rewrite module rewrites to a folder. For example, if substitution URL in rewrite rule is "/folder1/folder2" and these folders exist on file system and have default document configured, then DefaultDocument module will redirect web client to "/folder1/folder2/", thus exposing rewritten URL. To prevent this from happening, use "/" at the end of the substitution URL when rewriting to a folder, e.g. "/folder1/folder2/"

Related Content

• Articles
• URL Rewrite Module - Video Walkthrough
• Rule Templates Overview
• URL Rewrite for Hosters
• Provide URL Rewriting Functionality

Comments

You must Log In to comment.