URL Rewrite Module 2.1 URL Rewrite Module Rule Writing

Prerequisites
Setting up a test page
Creating Rewrite Rules
Naming convention
Defining the Mode
Defining actions
View the rewrite rules in the configuration file
Testing rewrite rules
Create redirection rules
Testing redirection rules
Creating an access blocking rule
Testing access blocking rules
summary

Prerequisites

This walkthrough requires the following prerequisites:

IIS installs URL Rewrite Module 2.1

Short URL http://www.iis.net/extensions/URLRewrite

Download Page

https://www.iis.net/downloads/microsoft/url-rewrite#additionalDownloads

Download Link

https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_en-US.msi

https://download.microsoft.com/download/1/2/8/128E2E22-C1B9-44A4-BE2A-5859ED1D4592/rewrite_amd64_zh-CN.msi

IIS 7 or later with the ASP.NET role service enabled.
The URL Rewrite module is installed. See Using the URL Rewrite Module for more information.

Setting up a test page

To demonstrate how the URL Rewrite module works, we will use a simple test ASP.NET page. This page reads web server variables and outputs their values in the browser.

Copy the following ASP.NET code and place it in the %SystemDrive%\inetpub\wwwroot\ folder in a file named 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 if the page renders correctly in the browser.

Creating Rewrite Rules

We will create a simple rewrite rule that will rewrite the URL using the following format:

http://localhost/article/342/some-article-title
to:
http://localhost/article.aspx?id=342&title=some-article-title.

We will create a rewrite rule using the URL Rewrite UI in IIS Manager. To do this, follow these steps:

1. Go to IIS Manager.

2. Select Default Website.

3. In Features View, click URL Rewrite.

4. In the Actions pane on the right, click Add Rule….

5. In the Add Rule dialog box, select Blank Rule, and then click OK.

Now you have to define the actual rewrite rules. In the URL rewriting module, rewriting rules are defined by specifying four required pieces of information:

Rule name.
Pattern to match against URL string.
An optional set of conditions.
The action to be performed when the pattern is matched and all condition checks succeed.

Naming convention

In the Name text box, enter a name that will uniquely identify this rule, for example: "Rewrite to article.aspx".

Defining the Mode

In the Pattern text box, enter the following string:

^article/([0-9]+)/([_0-9a-z-]+)

This string is a regular expression that specifies that the pattern will match any URL string that meets the following conditions:

Starts with the sequence of characters "article/".
Include one or more numeric characters after the first "/".
Contain one or more alphanumeric or "_" or "-" characters after the second "/".

Note that some parts of the regular expression are within parentheses. These parentheses create capturing groups that can be referenced later in the rule by using backreferences.

Defining actions

Since the rule we are going to create should rewrite URLs, select the “Rewrite action” type listed in the “Action” group box. In the "Rewrite URL:" text box, enter the following string:

article.aspx?id={R:1}&title={R:2}

This string specifies the new value that the input URL should be rewritten to. Note that for the values of the query string parameters, we used {R:1} and {R:2}, which are backreferences to the capturing groups defined in the rule pattern using parentheses.

Keep all other settings at their default values. The Edit Inbound Rules properties page should resemble the following:

Save the rule by clicking Apply on the right.

View the rewrite rules in the configuration file

Rewrite rules are stored in the ApplicationHost.config file or the Web.config file. To check the configuration of the rule we just created, open the Web.config file in %SystemDrive%\inetpub\wwwroot. In this file, you should see a <rewrite> section containing this rule definition:

<rewrite>
 <rules>
 <rule name="Rewrite to article.aspx">
  <match url="^article/([0-9]+)/([_0-9a-z-]+)" />
  <action type="Rewrite" url="article.aspx?id={R:1}&amp;title={R:2}" />
 </rule>
 </rules>
</rewrite>

The above syntax also applies to configuring URL rewriting in Web.config of Windows Azure Websites (WAWS).

Testing rewrite rules

To test that the rule is rewriting the URL correctly, open a web browser and request the following URL:

http://localhost/article/234/some-title

You should see that the rewrite rules on the web server have changed the original URL to Article.aspx, and that it has passed "234" and "some-title" as the values of the query string parameters.

Create redirection rules

Now, we will create a redirect rule that will redirect all URLs in the following format:

http://localhost/blog/some-other-title/543
The format is as follows:
http://localhost/article/543/some-other-title

Redirect rules allow more than one URL to point to a single web page.

To do this, open the URL Rewriting feature view UI in IIS Manager. Click Add Rule… and select the Blank Rule template again.

In the Edit Rule page, enter the following:

Name: Redirect from Blog (This is a unique name for the rule.)
Pattern: ^blog/([[_0-9a-z-]+)/([0-9]+) (This pattern will match a URL string that begins with "blog" and capture the second and third parts of the URL as backreferences.)
Action: Redirect (A redirect action will result in a redirect response being sent back to the browser.)
Redirect URL: article/{R:2}/{R:1} (This replacement string will be used as the redirect URL; note that it uses backreferences to preserve and rearrange the original URL captured during pattern matching.)

Enter a Name, Style, and Action as shown below:

Enter the redirect URL as shown below:

Keep all other settings at their default values. Save the rule by clicking Apply on the right.

Testing redirection rules

To test that the rule is redirecting requests correctly, open a web browser and request the following URL:

http://localhost/blog/some-other-title/323

You should see that the browser is redirected to http://localhost/article/323/some-other-title due to the execution of the redirect rule, and then the request is rewritten according to the rewrite rule you created earlier.

Creating an access blocking rule

The third rule we will create will block all requests to the website if they do not have a host header set. This type of rule is useful when you want to prevent hacking attempts that are made by making HTTP requests against the server's IP address instead of using the hostname.

We will create this rule without using IIS Manager. Open the Web.config file in the %SystemDrive%\inetpub\wwwroot\ folder that you used for the article.aspx test file at the beginning of this article. Find the <rewrite> section. Insert the following rule into the <rules> collection, making it the first rule in the collection:

<rule name="Fail bad requests">
 <match url=".*"/>
 <conditions>
 <add input="{HTTP_HOST}" pattern="localhost" negate="true" />
 </conditions>
 <action type="AbortRequest" />
</rule>

The <rewrite> section should resemble the following code:

<rewrite>
 <rules>
 <rule name="Fail bad requests">
  <match url=".*"/>
  <conditions>
  <add input="{HTTP_HOST}" pattern="localhost" negate="true" />
  </conditions>
  <action type="AbortRequest" />
 </rule>
 <rule name="Redirect from blog">
  <match url="^blog/([_0-9a-z-]+)/([0-9]+)" />
  <action type="Redirect" url="article/{R:2}/{R:1}" redirectType="Found" />
 </rule>
 <rule name="Rewrite to article.aspx">
  <match url="^article/([0-9]+)/([_0-9a-z-]+)" />
  <action type="Rewrite" url="article.aspx?id={R:1}&amp;title={R:2}" />
 </rule>
 </rules>
</rewrite>

Let's analyze the rule to understand what it does.

<match url=".*"/>

The above element indicates that this rule will match any URL string.

<add input="{HTTP_HOST}" pattern="localhost" negate="true" />

The above element adds a condition to the rule that retrieves the Host header value by reading the server variable HTTP_HOST, matching it against the pattern "localhost", and then negating the result. In other words, the condition verifies that the host header does not match "localhost".

<action type="AbortRequest" />

The above element tells the URL Rewrite module to end the HTTP request.

Testing access blocking rules

To test this rule, open a web browser and make a request to http://127.0.0.1/article/234/some-title. What you should see is the browser not receiving any response from the server. However, if you request http://localhost/article/234/some-title, the web server will respond successfully.

The failed display is as follows:

Success is displayed as follows:

summary

In this walkthrough, you learned how to configure URL rewrite rules by using IIS Manager or by manually editing the Web.config file. The rules created in this walkthrough demonstrate some important features of the URL Rewrite module, such as regular expression support and the ability to use HTTP headers and server variables to make rewriting decisions.

<<: Implementation of check constraints in MySQL 8.0

>>: Vue implements automatic jump to login page when token expires