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:
- ~ operator in ASP.NET Web server control is resolved incorrectly when using URL rewriting
- 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
References and guidance
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:
- Added string manipulation functions UrlEncode and UrlDecode.
- 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.
- Added UI for configuring rewrite rules for Application Request Routing.
- Added support for in-place upgrade from Go Live release of URL rewrite module.
- Added functionality to clean up the internal cache to avoid excessive usage of memory when caching rewrite rules.
- Fixed a bug related to rewriting of URLs that contain non-ASCII characters.
- Fixed a bug in regular expression engine that caused character ranges to be evaluated incorrectly for case insensitive patterns.
- Included an update for IIS FastCGI module into the installer package.
- Included an update for System.Web.dll into the installer package.
- Included an update for 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 “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}”.
- Digest authentication cannot be used with URL rewrite module.
- 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".
- 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".
- 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".
- 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.
- 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
Comments