The Basics: How to convert .htaccess to IIS (web.config)

Find an article
May 21
Published by in · Leave your thoughts
( words)
Warning! There was an error loading some of the images for this post.

This blog post primarily serves as a record for me but hopefully it may be useful to others too.  Often, we need to develop rewrite rules that work with more than one web server – after all, Apache is by no means the be-all-and-end-all.  In this case I’m going to focus on converting Apache .htaccess rules to IIS’s equivalent: web.config.

Before anything else, I recommend trying an automatic converter #lazy! Here’s some I found with a quick search:

If you’re able to setup IIS then you can also try Microsofts built-in converter: https://blogs.msdn.microsoft.com/azureossds/2015/04/23/converting-apache-htaccess-rules-to-iis-web-config-using-iis-manager-for-azure-websites/

 

Sadly in my case, I burst out in tears as none of the above worked. Conveniently that’s lead to this blog post.

Automation sucks, what now?

So the first step to producing a web.config file is you need to start with the below template:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <-- Rules to come later... -->
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Now we can start with the painful process of converting the rewrite rules to IIS’s xml-based format.

Rule Element

The <rule> element is the parent element that defines the match clause, conditions and action clause.

Attributes

The <rule> element can contain the following attributes:

Name Value Type Description Apache Equivalent
name string Human-readable name for the rule.
stopProcessing boolean Whether this should be the last rule.  [L]

Match Element

The <match> element is a child element of the <rule> and defines what the URL that should trigger the rule.

Attributes

The <match> element can contain the following attributes:

Name Value Type Description Apache Equivalent
url string Regular expression.  RewriteRule <url> <action>
ignoreCase boolean Whether this should be the last rule.  [NC]

Conditions Element

The <conditions> element is a child element of the <rule> and defines the conditions under which the rule should be matched. I’m not sure if there are other values for logicalGrouping but I found I have to create separate rules if my conditions were particularly complex e.g. (x AND y) OR (a AND b)

Attributes

The <conditions> element can contain the following attributes:

Name Value Type Description Apache Equivalent
logicalGrouping “MatchAll” or “MatchAny” Whether to match all or any of the conditions.  [OR]

Add Element

The <add> element is a child element of the <conditions> and defines each individual condition. This is equivalent to the RewriteCond directive in Apache.

Attributes

The <add> element can contain the following attributes:

Name Value Type Description Apache Equivalent
input string A server variable, a full list of supported variables can be found here.  RewriteCond <input> <pattern>
pattern string Regular expression.  RewriteCond <input> <pattern>

Action Element

The <action> element is a child element of the <rule> and defines what should happen when a rule is matched. This is the equivalent of the RewriteRule directive in Apache.

Attributes

The <action> element can contain the following attributes:

Name Value Type Description Apache Equivalent
type “Redirect” or “Rewrite” or “CustomResponse” or “AbortResponse” or “None” Type of action. Redirect = [R=301]
AbortReponse = [F]
url string Whether this should be the last rule. RewriteRule <pattern> <action>
appendQueryString boolean Whether the query string from the current URL should be preserved during substitution.
Defaults to true.
Only applicable to types: “Redirect” / “Rewrite”
[QSA]
redirectType “Permanent” or “Found” or “Temporary” Only applicable to type: “Redirect” [R=301]

 

For more reference on IIS rewrite module please read: https://www.iis.net/learn/extensions/url-rewrite-module/url-rewrite-module-configuration-reference

 

Leave a Reply

Your email address will not be published.