IIS URL Rewriting and ASP.NET Routing

With the release of the URL Rewrite Module for IIS and the inclusion of ASP.NET routing into the .NET Framework 4, there have been a lot of questions from ASP.NET developers about how these two features relate to each other and when you should use one or the other. This document describes the differences between these two technologies and provides guidance for Web developers about when to use IIS URL rewriting and when to use ASP.NET routing.

From a high-level perspective, it seems like these technologies provide very similar functionality—both allow your Web applications to have user-friendly and search-engine-friendly URLs. However, there are fundamental differences between these two technologies that are important to understand to make the right decision about what to use for your Web application. To help you understand those differences, we will first explain how IIS URL rewriting and ASP.NET routing work.

IIS URL Rewriting

The basic idea of URL rewriting is not a new concept. It was introduced in the Apache Web server about a decade ago. Since then it has proven to be a very useful tool for Web server administrators and Web developers. Many popular applications that are hosted on Apache now rely on URL rewriting to enable support for «clean» URLs.

The concept of URL rewriting is simple. When a client sends a request to the Web server for a particular URL, the URL rewriting module analyzes the requested URL and changes it to a different URL on the same server. The URL rewriting module runs early in the request-processing pipeline, modifying the requested URL before the Web server decides which handler to use to process the request. The handler, which is chosen based on the rewritten URL, processes the request and generates a response that is sent back to the Web browser. The requesting client never sees the rewritten URL; as far as the client is concerned, it has received a response from the original URL.

In terms of the IIS architecture, this process is represented by the following diagram:

The URL Rewrite module is a native code module that plugs into the request-processing pipeline at the Pre-begin Request or Begin Request stages, and then evaluates the requested URL path by using a set of rewrite rules. Each rewrite rule analyzes the URL path and, if all the rule conditions are met, changes the original path to a new path. After all the rules have been evaluated, the URL Rewrite module produces a final URL path that is used for the request through the remainder of the IIS pipeline processing. This means that the handler selection in the IIS pipeline is made based on the rewritten URL that is produced by the URL Rewrite module.

ASP.NET Routing

ASP.NET routing is a request-dispatching mechanism that lets developers associate a certain URL with a handler that can process requests made to that URL. This association is done by registering the «routes» that define which handler to invoke for a particular URL path. When a request is made to a Web server ASP.NET routing looks up the requested URL path in the list of registered routes. If the route is found, the corresponding handler for that route is invoked to process that request.

In terms of IIS and ASP.NET architecture, this process is represented by the following diagram:

ASP.NET routing is implemented as a managed-code module that plugs into the IIS request-processing pipeline at the Resolve Cache stage (PostResolveRequestCache event) and at the Map Handler stage (PostMapRequestHandler event). ASP.NET routing is configured to run for all requests made to the Web application.

During the PostResolveRequestCache event, the module looks through a routing table (a collection of route objects) for a route that matches the requested URL path. If a match is found, the module obtains a reference to the handler that corresponds to that route and saves the reference as part of the current HTTP context. A handler can be any .NET Framework object that implements the System.Web.IHttpHandler interface. If no route is found, the module does not do anything, and the URL falls through and is processed normally (typically by matching it to a file on disk).

During the PostMapRequestHandler event, the module checks if the HTTP context contains any information about a handler. If it does, ASP.NET routing uses the information to set the Handler property of the current HTTP context. This ensures that during the Execute Handler stage, IIS will execute the handler that was selected by the routing module. If that information is not set, then the module does not do anything and the URL falls through to let IIS make a handler selection.

Differences Between IIS URL Rewriting and ASP.NET Routing

Based on the above explanation, there are the following main conceptual differences between IIS URL rewriting and ASP.NET routing:

1. URL rewriting is used to manipulate URL paths before the request is handled by the Web server. The URL rewriting module does not know which handler will eventually process the rewritten URL. In addition, the actual request handler might not know that the URL has been rewritten.
2. ASP.NET routing is used to dispatch a request to a handler based on the requested URL path. As opposed to URL rewriting, the routing module knows about the handlers and selects the handler that should generate a response for the requested URL. You can think of ASP.NET routing as an advanced handler-mapping mechanism.

In addition to these conceptual differences, there are the following functional differences between IIS URL rewriting and ASP.NET routing:

1. The IIS URL Rewrite module can be used with any type of Web application, which includes ASP.NET, PHP, ASP, and static files. ASP.NET routing can be used only with .NET Framework-based Web applications.
2. The IIS URL Rewrite module works the same way regardless of whether integrated or classic IIS pipeline mode is used for the application pool. For ASP.NET routing, it is preferable to use integrated pipeline mode. ASP.NET routing can work in classic mode, but in that case the application URLs must include file name extensions or the application must be configured to use «*» handler mapping in IIS.
3. The IIS URL Rewrite module can make rewriting decisions based on domain names, HTTP headers, and server variables. By default, ASP.NET routing works only with URL paths and with the HTTP-Method header.
4. In addition to rewriting, the URL Rewrite module can perform HTTP redirection, issue custom status codes, and abort requests. ASP.NET routing does not perform these tasks.
5. The URL Rewrite module is not extensible in its current version. ASP.NET routing is fully extensible and customizable.

Which Option Should You Use?

What does all this information mean if you need to choose a technology to enable clean URLs for your Web applications? In this section, we explain how to make this choice.

If your Web application is built by using anything except ASP.NET, use the IIS URL Rewrite module. Otherwise, the rules are:

1. If you are developing a new ASP.NET Web application that uses either ASP.NET MVC or ASP.NET Dynamic Data technologies, use ASP.NET routing. Your application will benefit from native support for clean URLs, including generation of clean URLs for the links in your Web pages. Note that ASP.NET routing does not support standard Web Forms applications yet, although there are plans to support it in the future.
2. If you already have a legacy ASP.NET Web application and do not want to change it, use the URL Rewrite module. The URL Rewrite module lets you translate search engine-friendly URLs into a format that your application currently uses. Also, it lets you create redirect rules that can be used to redirect search engine crawlers to clean URLs.

In practice, however, the choice does not have to be either/or. The technologies can be used together and can complement each other. In the following sections, we outline some scenarios where you can use ASP.NET routing and IIS URL rewriting together.

Enforcing canonical URLs for your application.
You should force the use of http://www.mysite.com/home/about instead of http://mysite.com/Home/About. When a Web client requests a URL that does not conform to the format that you want, the client is redirected to a canonical URL. In this scenario, you can use the URL Rewrite module to enforce canonical URLs and perform redirection, and use ASP.NET routing to select a handler that would process the requested URL path.

The following example shows a URL rewrite rule that you can use for this scenario:

Serving static content from a different site or server.
Your Web application is deployed on multiple servers in such a way that dynamic Web content is located on one site or server and all static content is on a different site or server. You can use the URL Rewrite module together with the IIS Application Request Routing module to forward all requests for static files to a different server, while serving all requests for dynamic Web pages from the current server. This way, ASP.NET routing is used only for dynamic Web content and does not evaluate any URLs for static content.

The following example shows a URL rewrite rule that you can use for this scenario:

Static content management.
When your static files or folders are moved to a new location, you can still support old URLs for backward compatibility reasons. In fact, you might not want Web site visitors to know that the files or folders have been moved. In that case you can use URL Rewrite module to rewrite paths for static files, while all the URLs to your dynamic ASP.NET Web pages are handled by the routing module.

The following example shows a URL rewrite rule that you can use for this scenario:

Request blocking.
The URL Rewrite module can be used to block certain requests based on various criteria. For example, you can prevent certain site crawlers from accessing specific URL paths on your Web site. That way, forbidden requests will not even get to the ASP.NET router, thus reducing the load on your Web server.

The following example shows a URL rewrite rule that you can use to block unwanted site crawlers. Note that the requests are blocked for a particular URL path based on either the user-agent HTTP header or based on the client’s IP address:

URL Rewrite Module Configuration Reference

This article provides an overview of the URL Rewrite Module and explains the configuration concepts that are used by the module.

Functionality Overview

The URL Rewrite Module rewrites request URLs to simple, user-friendly, and search-engine friendly addresses that are displayed to users or in Web applications. URL Rewrite uses defined rules to evaluate and then map the request URL to the address defined in the rule before it is processed by an IIS Web server. You can define URL rewriting logic that includes regular expressions and wildcards, and rules can be applied based on the request URL, HTTP headers, and server variables. While the primary purpose of the module is to rewrite request URLs to more friendly URLs, you can also use the module to define rules that perform redirects, send custom responses, or abort requests.

Rewrite Rules Overview

A rewrite rule defines the logic of what to compare or match the request URL with, and what to do if the comparison is successful.

Rewrite rules consists of the following parts:

• Pattern – The rule pattern is used to specify either the regular expression or a wildcard pattern that is used to match URL strings.
• Conditions – The optional conditions collection is used to specify additional logical operations to perform if a URL string matches the rule pattern. Within the conditions, you can check for certain values of HTTP headers or server variables, or verify if the requested URL corresponds to a file or directory on a physical file system.
• Action – The action is used to specify what to do if the URL string matches the rule pattern and all the rule conditions are met.

Rewrite Rules Scope

Rewrite rules can be defined in two different collections:

• – Rules in this collection can be defined only on the server level. Global rules are used to define server-wide URL rewriting logic. These rules are defined within the ApplicationHost.config file, and they cannot be overridden or disabled on any lower configuration levels. Global rules always operate on the absolute URL’s path (that is, the requested URI without the server name). These rules are evaluated early in the IIS request-processing pipeline (PreBeginRequest event).
• – Rules in this collection are called distributed rules, and they can be defined on any level in the configuration hierarchy. Distributed rules are used to define URL rewriting logic specific to a particular configuration scope. This type of rule can be added on any configuration level by using Web.config files or by using tags within ApplicationHost.config or Web.config files. Distributed rules operate on the URL path, relative to the location of the Web.config file where they are defined. In cases where distributed rules are defined inside of a tag, they operate on the URL path, relative to the path specified for that tag. These rules are evaluated on the BeginRequest event in the IIS pipeline.

Rules Evaluation

Each configuration level in IIS can have zero or more rewrite rules defined. The rules are evaluated in the same order in which they are specified. The URL Rewrite Module processes the set of rules by using the following algorithm:

1. First, the URL is matched against the pattern of a rule. If it does not match, the URL Rewrite Module immediately stops processing that rule, and goes on to the next rule.
2. If a pattern matches and there are no conditions for the rule, the URL Rewrite Module performs the action specified for this rule and then goes on to the next rule, where it uses the substituted URL as an input for that rule.
3. If a pattern matches and there are conditions for the rule, the URL Rewrite Module evaluates the conditions. If the evaluation is successful, the specified rule action is performed, and then the rewritten URL is used as input to the subsequent rule

A rule may have the StopProcessing flag turned on. When the rule action is performed (i.e. the rule matched) and this flag is turned on, it means that no more subsequent rules will be processed and the request will be passed to the IIS request pipeline. By default, this flag is turned off.

Rules Inheritance

If rules are defined on multiple configuration levels, the URL Rewrite Module evaluates the rules in the following order:

1. Evaluate all the global rules.
2. Evaluate a rule set that includes distributed rules from parent configuration levels as well as rules from the current configuration level. The evaluation is performed in a parent-to-child order, which means that parent rules are evaluated first and the rules defined on a last child level are evaluated last.

Preserving Original URL

The URL Rewrite Module preserves the original requested URL path in the following server variables:

• HTTP_X_ORIGINAL_URL – this server variable contains the original URL in decoded format;
• UNENCODED_URL – this server variable contains the original URL exactly as it was requested by a Web client, with all original encoding preserved.

Accessing URL Parts from a Rewrite Rule

It is important to understand how certain parts of the URL string can be accessed from a rewrite rule.

For an HTTP URL in this form: http(s):// :

is matched against the pattern of the rule.

The is available in the server variable called QUERY_STRING and can be accessed by using a condition within a rule.

The is available in the server variable HTTP_HOST and can be accessed by using a condition within a rule.

The

is available in the server variable SERVER_PORT and can be accessed by using a condition within a rule.

Server variables SERVER_PORT_SECURE and HTTPS can be used to determine if a secure connection was used. These server variables can be accessed by using a condition within a rule.

The server variable REQUEST_URI can be used to access the entire requested URL path, including the query string.

For example, if a request was made for this URL: http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3 , and a rewrite rule was defined on the site level then:

• The rule pattern gets the URL string content/default.aspx as an input.
• The QUERY_STRING server variable contains tabid=2&subtabid=3 .
• The HTTP_HOST server variable contains www.mysite.com .
• The SERVER_PORT server variable contains 80 .
• The SERVER_PORT_SECURE server variable contains 0 and HTTPS contains OFF .
• The REQUEST_URI server variable contains /content/default.aspx?tabid=2&subtabid=3 .
• The PATH_INFO server variable contains /content/default.aspx .

Note that the input URL string passed to a distributed rule is always relative to the location of the Web.config file where the rule is defined. For example, if a request is made for http://www.mysite.com/content/default.aspx?tabid=2&subtabid=3 , and a rewrite rule is defined in the /content directory, then the rule gets this URL string default.aspx as an input.

Rewrite Rule Configuration

Rule Pattern

A rewrite rule pattern is used to specify a pattern to which the current URL path is compared. Current, in this context, means the value of the URL path when the rule is applied. If there were any rules that preceded the current rule, they may have matched the original requested URL and modified it. The URL string that is evaluated against the pattern does not include the query string. To include the query string in the rule evaluation you can use the QUERY_STRING server variable in the rule’s condition. For more information, refer to «Using server variables in rewrite rules».

A pattern is specified within a element of a rewrite rule.

Rule pattern syntax

Rule pattern syntax can be specified by using the patternSyntax attribute of a rule. This attribute can be set to one of the following options:

ECMAScript – Perl compatible (ECMAScript standard compliant) regular expression syntax. This is a default option for any rule. This is an example of the pattern format: «^([_0-9a-zA-Z-]+/)?(wp-.*)»

Wildcard – Wildcard syntax used in IIS HTTP redirection module. The following is an example of a pattern in this format: «/Scripts/*_in. «, where asterisk («*») means «match any number of any characters and capture them in a back-reference» and «?» means match exactly one character (no back-reference is created).

The scope of the patternSyntax attribute is per rule, meaning that it applies to the current rule’s pattern and to all patterns used within conditions of that rule.

Rule pattern properties

A pattern can be negated by using the negate attribute of the element. When this attribute is used, the rule action is performed only if the current URL does not match the specified pattern.

By default, case-insensitive pattern matching is used. To enable case sensitivity, you can use the ignoreCase attribute of the element of the rule.

Rule conditions

Rule conditions allow defining additional logic for rule evaluation, which can be based on inputs other than just a current URL string. Any rule can have zero or more conditions. Rule conditions are evaluated after the rule pattern match is successful.

Conditions are defined within a collection of a rewrite rule. This collection has an attribute called logicalGrouping that controls how conditions are evaluated. If a rule has conditions, then the rule action is performed only if rule pattern is matched and:

• All conditions were evaluated as true, provided that logicalGrouping=»MatchAll» was used.
• At least one of the conditions was evaluated as true, provided that logicalGrouping=»MatchAny» was used.

A condition is defined by specifying the following properties:

Condition input specifies which item to use as an input for the condition evaluation. Condition input is an arbitrary string that can include server variables and back-references to prior condition patterns and/or to rule patterns.

The match type can be one of the following three options:

IsFile – This match type is used to determine whether the input string contains a physical path to a file on a file system. If a condition input string is not specified, the URL Rewrite Module uses the physical path of the requested file as a default value for the condition input. This match type can be used only for distributed rules.

IsDirectory – This match type is used to determine whether the input string contains a physical path to a directory on a file system. If a condition input string is not specified, the URL Rewrite Module uses the physical path of the requested file as a default value for the condition input. This match type can be used only for distributed rules.

Pattern – This match type is used to express a condition where an arbitrary input string is matched against a regular expression pattern. A condition pattern can be specified by using either regular expression syntax or by using wildcard syntax. The type of pattern to use in a condition depends on the value of the patternSyntax flag defined for the rule to which this condition belongs. This condition type has two related attributes that control pattern matching:

• pattern – Use this attribute to specify the actual pattern.
• ignoreCase – Use this attribute to control whether pattern matching for the condition should be case sensitive or case insensitive.

In addition, the result of the condition evaluation can be negated by using the negate attribute. This can be used to specify a condition that checks if the requested URL is NOT a file, as in the following example:

Rule action

A rewrite rule action is performed when the current URL matches the rule pattern and the condition evaluation succeeded (depending on the rule configuration, either all conditions matched or any one or more of the conditions matched). There are several types of actions available, and the type attribute of the configuration element can be used to specify which action the rule performs. The following sections describe different action types and the configuration options related to specific action types.

Rewrite action

A Rewrite action replaces the current URL string with a substitution string. A substitution string must always specify the URL path (for example, contoso/test/default.aspx). Note that substitutions that contain a physical path on a file system (for example, C:\inetpub\wwwroot ) are not supported in IIS.

A Rewrite action has the following configuration options:

url – This is the substitution string to use when rewriting the current URL. The substitution URL is a string value that can include the following:

• Back-references to the condition and rule patterns. (For more information, see the section about how to use back-references.)
• Server variables. (For more information, see the section about how to use server variables.)

appendQueryString – Specifies whether the query string from the current URL is preserved during substitution. By default, if the value of the appendQueryString flag is not specified, it is assumed to be TRUE. This means that the query string from the original URL is appended to the substituted URL.

Redirect action

A Redirect action instructs the URL Rewrite Module to send a redirect response back to the client. The redirect status code (3xx) can be specified as a parameter for this action. The Location field of the response contains the substitution string specified in the rule.

The substitution URL for the redirect rule can be specified in one of the following forms:

• Relative URL path – contoso/test/default.aspx
• Absolute URI – https://example.com/contoso/test/default.aspx

Usage of a Redirect action implies that no subsequent rules evaluated for the current URL after redirection is performed.

A Redirect action has the following configuration options:

url – Uses a substitution string as a redirection URL. A substitution URL is a string that can include the following:

• Back-references to the condition and rule patterns. (For more information, see the section about how to use back-references.)
• Server variables. (For more information, see the section about how to use server variables.)

appendQueryString – Specifies whether the query string from the current URL should be preserved during substitution. By default, if the AppendQueryString flag is not specified, it is assumed to be TRUE. This means that the query string from the original URL is appended to the substituted URL.

redirectType – Specifies the status code to use during redirect:

• 301 – Permanent
• 302 – Found
• 303 – See other
• 307 – Temporary

CustomResponse action

A CustomResponse action causes the URL Rewrite Module to respond to the HTTP client by using a user-specified status code, subcode, and reason. Use of a CustomResponse action implies that no subsequent rules are evaluated for the current URL after this action is performed.

CustomResponse action has the following configuration options:

• statusCode– Specifies the status code to use in response to the client.
• subStatusCode – Specifies the substatus code to use in response to the client.
• statusReason – Specifies the reason phrase to use with the status code.
• statusDescription – Specifies the one line description to put in the body of the response.

AbortRequest action

An AbortRequest action causes the URL Rewrite Module to drop the HTTP connection for the current request. The action does not have any parameters. Use of this action implies that no subsequent rules are evaluated for the current URL after this action is performed.

None action

A None action is used to specify that no action is performed.

Using server variables in rewrite rules

Server variables provide additional information about current HTTP requests. You can use this information to make rewriting decisions or to compose the rewritten URL. Server variables can be referenced in the following locations within rewrite rules:

In the condition input string

In rule substitution strings, specifically:

• url attribute of Rewrite and Redirect action
• statusLine and responseLine of a CustomResponse action

Server variables can be referenced by using the syntax. For example, the following condition uses the QUERY_STRING server variable:

Server variables can also be used to access HTTP headers from the current request. Any HTTP header supplied by the current request is represented as a server variable that has a name generated in accordance to this naming convention:

1. All dash («-«) symbols in the HTTP header name are converted to underscore symbols («_»).
2. All letters in the HTTP header name are converted to capital case.
3. «HTTP_» prefix is added to the header name.

For example, in order to access the HTTP header «user-agent» from a rewrite rule, you can use the server variable.

Using back-references in rewrite rules

Parts of rules or conditions inputs can be captures in back-references. These can be then used to construct substitution URLs within rules actions or to construct input strings for rule conditions.

Back-references are generated in different ways, depending on which kind of pattern syntax is used for the rule. When an ECMAScript pattern syntax is used, a back-reference can be created by putting parenthesis around the part of the pattern that must capture the back-reference. For example, the pattern (3+)/([a-z]+).html will capture 07 and article in back-references from this requested URL: 07/article.html. When «Wildcard» pattern syntax is used, the back-references are always created when an asterisk symbol (*) is used in the pattern. No back-references are created when «?» is used in the pattern. For example the pattern */*.html will capture contoso and test in back-references from this requested URL: contoso/test.html.

Usage of back-references is the same regardless of which pattern syntax was used to capture them. Back-references can be used in the following locations within rewrite rules:

In condition input strings

In rule actions, specifically:

• url attribute of Rewrite and Redirect action
• statusLine and responseLine of a CustomResponse action

In a key parameter to the rewrite map

Back-references to condition patterns are identified by where N is from 0 to 9. Back-references to rule patterns are identified by where N is from 0 to 9. Note that for both types of back-references, and , will contain the matched string.

For example, in this pattern:

For the string: www.foo.com the back-references will be indexed as follows:

Within a rule action, you can use the back-references to the rule pattern and to the last matched condition of that rule. Within a condition input string, you can use the back-references to the rule pattern and to the previously matched condition.

The following rule example demonstrates how back-references are created and referenced:

Interaction with IIS Output Caching

The URL Rewrite Module controls the IIS output cache behavior in order to:

1. Optimally utilize kernel mode and user mode output caching of responses for rewritten URLs, thus improving performance of the Web application that uses URL Rewrite Module.
2. Prevent caching of responses, when caching logic may be violated due to URL rewriting.

The module controls output caching either by altering certain caching properties or by disabling the caching altogether. The module cannot enable output caching if it has been disabled by IIS configuration or by any other module in the IIS pipeline. The output caching is controlled as follows:

The module always sets the user mode cache setting varyByHeader=»HTTP_X_ORIGINAL_URL». This ensures that when user mode caching is enabled the module takes into account the original URL to construct a key for the cache entry.

If a rewrite rule set uses server variables with values that are either constant throughout the life of the process or are derived from the requested URL, the rule set is considered safe for output caching. This means that the URL Rewrite Module will not alter existing caching policy in any way other than setting varyByHeader as described in step 1.

The following server variables, when used in rewrite rules, do not cause any effect on output caching policy:

• «CACHE_URL»
• «DOCUMENT_ROOT»
• «HTTP_URL»
• «HTTP_HOST»
• «PATH_INFO»
• «PATH_TRANSLATED»
• «QUERY_STRING»
• «REQUEST_FILENAME»
• «REQUEST_URI»
• «SCRIPT_FILENAME»
• «SCRIPT_NAME»
• «SCRIPT_TRANSLATED»
• «UNENCODED_URL»
• «URL»
• «URL_PATH_INFO»
• «»APP_POOL_ID»
• «APPL_MD_PATH»
• «APPL_PHYSICAL_PATH»
• «GATEWAY_INTERFACE»
• «SERVER_SOFTWARE»
• «SSI_EXEC_DISABLED»

If a rewrite rule set uses any server variable not mentioned in the above list, the rule set is considered unsafe for output caching. This means that the URL Rewrite Module will disable kernel mode caching for all requests whether the request URLs were rewritten or not. In addition, the module will alter the caching policy for user-mode cache by setting the caching property varyByValue to contain the concatenated string of all server variables values used in the rule set.

String functions

There are three string functions available for changing the values within a rewrite rule action, as well as any conditions:

• ToLower — returns the input string converted to lower case.
• UrlEncode — returns the input string converted to URL-encoded format. This function can be used if the substitution URL in rewrite rule contains special characters (for example non-ASCII or URI-unsafe characters).
• UrlDecode — decodes the URL-encoded input string. This function can be used to decode a condition input before matching it against a pattern.

The functions can be invoked by using the following syntax:

Where «function_name» can be on eof the following: «ToLower», «UrlEncode», «UrlDecode». «Any_string» can be either a literal string or a string built by using server variables or back-references. For example, the following are valid invocations of string functions:

The string functions can be used in the following locations within rewrite rules:

In condition input strings

In rule substitution strings, specifically:

• url attribute of Rewrite and Redirect actions
• statusLine and responseLine attributes of a CustomResponse action

An example of a rule that uses the ToLower function:

An example of a rule that uses the UrlEncode function:

An example of a rule that uses the UrlDecode function:

Rewrite maps

A 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 and all of these rules use static strings (that is, when 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 into the rewrite map as keys and values between the input URL and the substitution URL. Then, to look up the substitution URL based on the input URL, you will have one rewrite rule that references the rewrite map.

A rewrite map defines a named collection of name-value pair strings, as in the following example:

A rewrite map is uniquely identified by its name and can contain zero or more key-value entries. In addition, a rewrite map can specify the default value to use when a key is not found. This is controlled by using the defaultValue attribute. By default, an empty string is used as a default value.

There can be any number of rewrite maps on any configuration level, except the file level. Rewrite maps are located within collection element.

Rewrite maps are referenced within a rewrite rule by using the following syntax:

Where the Key parameter can be any arbitrary string, and can include back-references to rule or condition patterns. For example, the following are valid uses of a rewrite map:

A reference to a rewrite map gets substituted with the value that was looked up by using the key passed as a parameter within a rewrite map reference. If a key was not found, the default value for that rewrite map is used.

A Rewrite map can be referenced in the following locations within rewrite rules:

In condition input string

In rule substitution strings, specifically:

• url attribute of Rewrite and Redirect actions
• statusLine and responseLine of CustomResponse actions

Example 1: With a rewrite map defined as follows:

And a rewrite rule defined as follows:

Example 2: With a rewrite map defined as follows: