Rule with Rewrite Map - rule template

by Ruslan Yakushev

Rule templates are used to provide a simple way of creating one or more rewrite rules for a certain scenario. URL rewriter module includes several rule templates for some common usage scenarios. In addition to that URL rewrite module UI provides a framework for plugging in custom rule templates. This walkthrough will guide you through how to use "Rule with Rewrite Map" template that is included with URL rewrite module.

Prerequisites

This walkthrough requires the following prerequisites:

  1. IIS 7.0 or above with ASP.NET role service enabled;
  2. URL rewrite module Go Live release installed.

Setting up a test web page

We will be using a simple test asp.net page to verify that the rule created by the template works correctly. The test page simply reads the web server variables and outputs their values in browser.

Copy the following ASP.NET code and put it in the %SystemDrive%\inetpub\wwwroot\ folder in a file called article.aspx:

<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>URL Rewrite Module Test</title>
</head>
<body>
      <h1>URL Rewrite Module Test Page</h1>
      <table>
            <tr>
                  <th>Server Variable</th>
                  <th>Value</th>
            </tr>
            <tr>
                  <td>Original URL: </td>
                  <td><%= Request.ServerVariables["HTTP_X_ORIGINAL_URL"] %></td>
            </tr>
            <tr>
                  <td>Final URL: </td>
                  <td><%= Request.ServerVariables["SCRIPT_NAME"] + "?" + Request.ServerVariables["QUERY_STRING"] %></td>
            </tr>
      </table>
</body>
</html>

After copying this file, browse to http://localhost/article.aspx and check that the page was rendered correctly in a browser.

Screenshot of the U R L Rewrite Module Test Page webpage.

Using rule template to generate rewrite rule

The "Rule with Rewrite Map" template can be used to generate rewrite and redirect rules that use rewrite maps for storing static mappings between originally requested URLs and rewritten or redirected URLs. For more information about usage of rewrite maps refer to "URL Rewrite Module Configuration Reference" and "Using Rewrite Maps in URL Rewrite Module".

To use this template follow these steps:

  1. Go to IIS Manager

  2. Select "Default Web Site"

  3. In the Feature View click "URL Rewrite"
    Screenshot of the Default Web Site Home screen with the U R L Rewrite option being highlighted.

  4. In the "Actions" pane on right hand side click on "Add rules…"
    Screenshot of the U R L Rewrite screen with a focus on the Add Rules option.

  5. In the "Add Rules" dialog select "Rule with Rewrite Map" and click "OK":
    Screenshot of the Add rules dialog with the Rule with rewrite map option being highlighted.

  6. In the "Add rule with rewrite map" dialog, choose "Rewrite" in the drop down list. In the "Choose the rewrite map:" combo box specify the name of the new rewrite map as StaticRewrites.
    Screenshot of the Add rule with rewrite map dialog.

  7. Click "OK". This will create a rewrite map with the given name and a rewrite rule with name "Rewrite Rule 1 for StaticRewrites" that references that rewrite map.

  8. After clicking "OK" you will be taken to the page where you can specify the mapping entries for the rewrite map. Click on "Add Mapping Entry..." in the Actions pane on right hand side and then enter the original and new value for the mapping entry as "/article1" and "/article.aspx?id=1&title=some-title" respectively.
    Screenshot of the Add Mapping Entry dialog showing the Original value and New value fields.

  9. Repeat previous step to add two more mapping entries as follows:

    Original Value: New Value:
    /some-title /article.aspx?id=1&title=some-title
    /post/some-title.html /article.aspx?id=1&title=some-title

After completing these steps you should see the following rewrite map and rewrite rule created in C:\inetpub\wwwroot\web.config file.

<rewrite>
    <rewriteMaps>
        <rewriteMap name="StaticRewrites">
            <add key="/article1" value="/article.aspx?id=1&amp;title=some-title" />
            <add key="/some-title" value="/article.aspx?id=1&amp;title=some-title" />
            <add key="/post/some-title.html" value="/article.aspx?id=1&amp;title=some-title" />
        </rewriteMap>
    </rewriteMaps>
    <rules>
        <rule name="Rewrite Rule 1 for StaticRewrites" stopProcessing="true">
            <match url=".*" />
            <conditions>
                <add input="{StaticRewrites:{REQUEST_URI}}" pattern="(.+)" />
            </conditions>
            <action type="Rewrite" url="{C:1}" appendQueryString="False"/>
        </rule>
    </rules>
</rewrite>

Testing the rule

To test the generated rewrite rule that uses the "StaticRewrites" map, open web browser and request any of the following URLs:

http://localhost/article1
http://localhost/some-title
http://localhost/post/some-title.html

Any one of the URLs above should cause the URL to be rewritten in accordance to the mappings defined in the rewrite map. Your results should look like the following page:

Screenshot of the U R L Rewrite Module Test Page showing the Original U R L and Final U R L fields.

Summary

In this walkthrough you have learned how to generate rewrite rules with rewrite maps by using "Rule with Rewrite Map" template included with URL rewrite module. This rule template can be used for creating a rule and a placeholder map that can contain large number of static rewriting and redirection mappings for your web application.