Upravit

Sdílet prostřednictvím

Using URL Rewrite Module 2.0

  • Článek

by Ruslan Yakushev

Introduction

This section of the documentation applies to the URL Rewrite 2.0 for IIS 7.

URL Rewrite 2.0 for IIS 7 and above is an incremental release that includes all the features from version 1.1, and adds support for .NET extensibility and for outbound response rewriting. More specifically, it can be used to:

  • Implement complex rewrite logic by using rewrite providers written in .NET
  • Replace the URLs generated by a web application in the response HTML with a more user friendly and search engine friendly equivalent
  • Modify the links in the HTML markup generated by a web application behind a reverse proxy.
  • Fix up the content of any HTTP response by using regular expression pattern matching.
  • Modify HTTP request and response headers and IIS server variables.

Features

URL Rewrite 2.0 includes the following key features:

  • Custom rewrite providers (new in RTW). The rewrite providers can be used when an URL rewrite logic cannot be expressed in terms of regular expression patterns or when it is required to make rewriting decisions based on data stored outside of web.config file (e.g. SQL database or text files). Customer rewrite providers can be implemented in any .NET language.
  • Rules-based response rewriting engine. Outbound rules are used to express the logic of what to compare parts of the response with and what to do if comparison was successful. Web server and site administrators can use outbound rules to define complex response rewriting logic.
  • Rewriting within the content of specific HTML tags. Instead of scanning the entire response for a particular match, the rule can be configured to look only inside of certain HTML tags, such as <a>, <img>, etc. That way the pattern is greatly simplified and the process of applying the rule to the content is much faster comparing to applying the pattern to the entire response.
  • Pre-conditions for outbound rules. Applying rewrite rules on every response is an expensive operation and is not necessary in majority of the cases. Pre-conditions are used to check the response metadata to determine if outbound rules evaluation should be applied.
  • Rewriting of server variables and HTTP request headers. Various IIS server variables and HTTP request headers can be set by using rewrite rules.
  • Rewriting of HTTP response headers. Outbound rewrite rules can be used modify any existing HTTP response headers or to set new ones.
  • Allow list for server variables. To prevent distributed rewrite rules from accidentally or purposefully modifying IIS server variables that may affect security or runtime behavior of a web application the modifiable server variables now have to be explicitly added to the allow list.
  • HtmlEncode function. Outbound rewrite may often use an un-trusted data (e.g. query string or HTTP headers) to build a replacement string to insert into the HTTP response. In those cases the HtmlEncode function should be used to prevent insertion of client-side scripts into the response, which could result in cross-site scripting vulnerability.
  • Tracking capture groups across rule conditions. The conditions back-referencing logic in URL Rewrite 1.1 worked only against the last matched conditions. In v2 it is possible to configure back-referencing logic to work against all matched conditions.
  • Rule templates for Search Engine Optimization (new in RTW). Three new rule templates make it very easy to create redirect rules that will enforce usage of canonical URLs for web pages on your site.
  • Reverse Proxy rule template (new in RTW). This template can be used to very quickly generate inbound and outbound rewrite rules that implement reverse proxy configuration.
  • Logging of rewritten URLs. The rewrite rules can be configured to log the rewritten URL in IIS W3C logs as opposed to logging an originally requested URL.
  • Updated user interface in IIS Manager. The user interface has been significantly improved to better represent the module configuration and to simplify such common tasks as configuring of rewrite rules and rewrite conditions.

Installing the module

Download the URL Rewrite 2.0 by using the links at the module's home page at https://www.iis.net/extensions/urlrewrite

Note

  • If a previous version of URL Rewrite, such as v1.0 and v1.1, is already installed then it will be upgraded to the v2.0
  • If an RC version of the URL Rewrite 2.0 is already installed, then it will be upgraded to RTW version.

Known Issues

  1. Response rewriting does not work with static compression. You will have to disable IIS static compression in order to use response rewriting.
  2. Outbound rules are not applied to chunked transfer encoded responses if rewriteBeforeCache is enabled. Set rewriteBeforeCache to false if you need to rewrite responses that are chunked transfer encoded.

Installing the extensibility samples

The URL Rewrite Extensibility Samples include the .NET assemblies and the source code implementing these providers:

  • DbProvider - this provider can be used to retrieve rewrite mappings from a SQL Server database table by executing a stored procedure;
  • FileMapProvider - this provider can be used to retrieve rewrite mappings stored in a text file;
  • FileContainsProvider - this provider can be used to check if any string in a text file is a substring of the provider's input string.

Download the URL Rewrite Extensibility Samples from MSDN Code Gallery.

Using the module

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

Walkthroughs

Functionality reference