Configuration and Application of IIS URL Rewrite Module in Web.config

Overview of IIS URL Rewrite Module

The IIS URL Rewrite Module is an extension component for Microsoft IIS servers, enabling advanced URL processing features such as URL rewriting and redirection. This module supports defining rewrite rules in Web.config files through XML configuration, allowing URL transformation without modifying application code.

Web.config File Location and Basic Structure

The Web.config file should be placed in the root directory of the website. For IIS servers, this is typically located in the website's main directory, such as %SystemDrive%\inetpub\wwwroot\ or user-defined website directories. The basic file structure includes the <configuration> root element, with the <system.webServer> section used for configuring IIS-related settings.

Differences Between Rewrite Rules and Redirect Rules

URL rewriting and redirection are two distinct URL processing methods:

• Rewrite: The server internally maps the request URL to another resource, with the browser address bar displaying the original URL unchanged
• Redirect: The server returns an HTTP redirect response, causing the browser to automatically navigate to the new URL, with the address bar updating to show the new location

Specific Rule Configuration Examples

Single Exact Rewrite Rule

The following rule implements exact rewriting from /page to /page.html, keeping the URL unchanged in the browser:

<system.webServer>
    <rewrite>
        <rules>
            <rule name="SpecificRewrite" stopProcessing="true">
                <match url="^page$" />
                <action type="Rewrite" url="/page.html" />
            </rule>
        </rules>
    </rewrite>
</system.webServer>

Rule analysis: stopProcessing="true" indicates that subsequent rule processing stops after matching this rule; ^page$ is a regular expression matching the exact "page" path; type="Rewrite" specifies the rewrite action type.

Single Exact Redirect Rule

The following rule implements a 301 permanent redirect from /page to /page.html:

<system.webServer>
    <rewrite>
        <rules>
            <rule name="SpecificRedirect" stopProcessing="true">
                <match url="^page$" />
                <action type="Redirect" url="/page.html" />
            </rule>
        </rules>
    </rewrite>
</system.webServer>

The main difference from the rewrite rule is type="Redirect", which sends a redirect response to the browser.

Dynamic Rewrite Rule

The following rule implements dynamic rewriting, automatically looking for corresponding .html files for any URL:

<system.webServer>
    <rewrite>
        <rules>
            <rule name="DynamicRewrite" stopProcessing="true">
                <match url="(.*)" />
                <conditions>
                    <add input="{REQUEST_FILENAME}\.html" matchType="IsFile" />
                </conditions>
                <action type="Rewrite" url="/{R:1}.html" />
            </rule>
        </rules>
    </rewrite>
</system.webServer>

Rule analysis: (.*) matches any URL path; the condition {REQUEST_FILENAME}\.html checks if the corresponding .html file exists; {R:1} references the first capture group from the regular expression.

Common Issues and Solutions

Configuration Location Issues

The Web.config file must be placed in the website root directory or specific application directories. If placed in the wrong location, rules will not take effect. It is recommended to use IIS Manager to verify the correct file placement.

Using Rewrite Maps

The original question used <rewriteMap> but did not create rules utilizing the map. Rewrite maps themselves do not perform any operations and must be used in conjunction with rules:

<rewriteMaps>
    <rewriteMap name="StaticRedirects">
        <add key="/page" value="/page.html" />
    </rewriteMap>
</rewriteMaps>

Corresponding rules need to be created to reference the key-value pairs in the map.

Permissions and Module Installation

Ensure that the URL Rewrite Module is installed on the IIS server and that the application pool has sufficient permissions to execute rewrite operations. This can be verified through IIS Manager to check if the module is installed and enabled.

Advanced Configuration Techniques

Using Conditions for Complex Matching

The URL Rewrite Module supports using conditions for more precise matching control:

<conditions>
    <add input="{HTTP_HOST}" pattern="^example\.com$" />
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
</conditions>

This condition combination ensures the rule only takes effect when accessing the example.com domain and the request is not for an actual file.

Rule Execution Order

Rules are executed in the order they appear in the configuration file. Using stopProcessing="true" can optimize performance by stopping subsequent rule processing after a match is found.

Testing and Verification

After configuration, test URLs should be accessed through a browser to verify that rules work correctly. Browser developer tools can be used to observe network requests and confirm whether rewriting or redirection executes as expected. For rewrite rules, the server variable HTTP_X_ORIGINAL_URL can display the original request URL.

Best Practices

• Provide meaningful names for each rule to facilitate maintenance
• Thoroughly test all rules in development environments
• Use regular expression testing tools to verify pattern matching
• Consider performance impact and avoid overly complex regular expressions
• Regularly review and optimize rewrite rule configurations

By properly configuring the IIS URL Rewrite Module, website URL structure can be significantly improved, enhancing user experience and search engine optimization results. Understanding the differences and appropriate scenarios for rewriting versus redirection is key to effectively using this module.