Using the URL Rewrite Module

About the URL Rewrite module

The Microsoft URL Rewrite Module 2.0 for IIS 7 and above enables IIS administrators to create powerful customized rules to map request URLs to friendly URLs that are easier for users to remember and easier for search engines to find. You can use the URL Rewrite module to perform URL manipulation tasks, some of which include:

Perform redirects, send custom responses, or stop HTTP requests based on the logic expressed in the rewrite rules.

Control access to Web site content based on URL segments or request metadata.

The URL Rewrite module is available both as a download that you can install on your own IIS server, and on Microsoft's Azure Web Sites cloud platform.

URL Rewrite 2.0 features

The Microsoft URL Rewrite module 2.0 includes the following key features:

Rules-based URL rewriting engine. Rewrite rules define the logic used to analyze request URLs and map them to rewite URLs when the request URL matches a defined rule. Web server and site administrators can use rewrite rule sets to define URL rewriting logic.

Global and distributed rewrite rules. URL Rewrite uses global rules to define server-wide URL rewriting logic. These rules are defined within the applicationHost.config file, and they supercede rules configured at lower levels in the configuration hierarchy. The module also uses distributed rules to define URL rewrite logic specific to a particular configuration scope. This type of rule 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 requests. This information can be used to configure rewrite rules 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 clients.

Support for IIS kernel mode and user mode output caching. IIS output caching provides significant performance improvements for Web applications. The 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. A rewrite map is an arbitrary collection of name-value pairs. You can use a rewrite map within rewrite rules to generate the substitution URL. 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 into the rewrite map using the input URL as a key, and the substitution URL as value. You can then have one rewrite rule that references the rewrite map to look up substitution URL based on the input URL.

Rule templates. A rule template is an extension for the URL Rewrite module user interface that simplifies creation of rewrite rules for a particular task. The module includes 3 rule templates, and also supports plugging in any number of custom templates.

User Interface (UI) for testing regular expression and wildcard patterns. A UI for testing rule patterns is provided with the module. Using the UI, you can quickly check the results of a regular expression or wildcard pattern in a rewrite rule. You can also use the UI for troubleshooting and debugging 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 the URL Rewrite Module from the IIS Manager.

UI for importing mod_rewrite rules. The URL Rewrite module includes a UI for converting rewrite rules from mod_rewrite format into an IIS format.

Where to get the URL Rewrite module

Upgrading from Go Live release

If you already have the Go Live release of URL rewrite module installed the installation package will upgrade it to URL Rewrite version 2.0. All rewrite rules in your 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 the URL Rewrite module. SPecifically, the update contains fixes for the following bugs:

~ operator in ASP.NET Web server control is resolved incorrectly when using URL Rewrite.

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 you install the required version of the .NET Framework after you install the URL Rewrite module, you can apply the ASP.NET update by running the URL Rewrite module installer and then selecting the Repair option in the installer dialog.

Included an update for the IIS SetUri function into the installer package.

Known Issues

mod_rewrite rules that use REQUEST_URI server variables may not work correctly when imported by using URL Rewrite the Import Rules feature. To fix the imported rules use, you can 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 the string “{SCRIPT_NAME}” with the string “{URL}”.

Digest authentication cannot be used with URL Rewrite module.

ASP.NET Forms authentication uses rewritten URL for redirection. For example, if the requested URL is "/article.htm" and the 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".

Auto-detect mode in ASP.NET Forms authentication uses a rewritten URL for redirection. For example, if the requested URL is "/article.htm" and the 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".

UseUri mode in ASP.NET Forms authentication uses rewritten URL for redirection. For example, if the 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".

ASP.NET rewrites back to the original URL when using URI-based authentication or cookie-less session state. For example, when a 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.

The IIS DefaultDocument module may redirect to a rewritten URL when the URL Rewrite module rewrites to a folder. For example, if the substitution URL in a rewrite rule is "/folder1/folder2" and these folders exist on the file system and have a Default document configured, then the DefaultDocument module will redirect Web clients to "/folder1/folder2/", thus exposing the rewritten URL. To prevent this from happening, use "/" at the end of the substitution URL when rewriting to a folder, for example, "/folder1/folder2/"