How to Use IIS Rewrite and Redirect Rules – Windows ASP.NET Core Hosting 2023 | Review and Comparison

I have read the question on Stackoverflow that many people about how to redirect 1 domain to other domains. So, in this post, it will cover about this tutorial.

What is the IIS rewrite module?

The rewrite module for IIS can be used to execute 2 actions:

  • rewrite => the URL stays the same but the content is loaded from somewhere else
  • redirects => when the user’s browser is taken to a new URL

Both use the same rules and conditions to determine if the action should be triggered or not and this article will mainly focus one those.

A rule can be as simple as:

<rule name="Redirect to github">
  <match url="^code$" />
  <action type="Redirect" url="" />

This rule checks if the requested path is exactly code (as in the URL and if it is the case, redirects the user to

Back references

Now, the interesting part is when you start using back references. If you want your action to depend on a part (or all) of the requested URL, you can use back references to recall those values.

Let’s look at the following example:

<rule name="Redirect to backreference">
  <match url="^(.*)$" />
  <action type="Redirect" url="https://{R:1}.com" />

If we look at the pattern being used: ^(.*)$:

  • The first character ^ means that the test will start at the beginning of the path.
  • The following sequence (.*) will capture any character.
  • The last character $ means that the test stops at the end of the path.

Important: The rule is only applied to the path; don’t let the name url fool you. (for example, in, the scheme and domain name are ignored for the “url” matching)

We now want to use the value captured in the test for the redirect. That’s when the back reference, {R:1}, comes to help.
The {R:1} part will contain whatever is captured inside the (.*) sequence during the test.
We could use {R:0} as well, since is contains the whole input string.

If we apply for example the URL to this rule, {R:1} will contain github.
It means that combined with the action, a user reaching will ultimately be redirected to

Taking back the example from my answer on stackoverflow:

Using the pattern ^(www\.)(.*)$ and the input string, you will have:

{R:0} -
{R:1} - www.
{R:2} -

The 0 reference always contains the full input while the 1 will contain the first part of the string matching the pattern in the first parenthesis (), the 2 reference the second one, etc…up to the reference number 9.


When you add conditions to your rule, you get access to more data from the request.
Let’s one more time take an example:

<rule name="Redirect to backreference with domain">
  <match url="^(.*)$" />
      <add input="{HTTP_HOST}" pattern="^.+$" />
  <action type="Redirect" url="https://{R:1}.com?ref={C:0}" />

This rule does the same as the previous one but it affects the original requested domain name to a ref variable in the querystring. We get the domain name by using the pattern ^.+$ (one or more characters) against the {HTTP_HOST} input. We are using {C:0} in this case. C stands for Conditions (against R for Rule) and 0 simply means the whole input value.


  • you can use the captured value in the rule (for example {R:1}) inside conditions.
  • if you have multiple conditions, the back reference used in the action refers only to the last matching one.
  • you can however use a back reference from a previous condition inside one.
<rule name="Redirect to backreference with domain">
  <match url=".*" />
      <add input="{HTTP_HOST}" pattern="^.+$" />
      <add input="{C:0}_{QUERY_STRING}" pattern="^.+$" />
  <action type="Redirect" url="{C:0}" />

In this case, the back reference {C:0} used in the action contains the last matched condition (<add input="{C:0}_{QUERY_STRING}" pattern="^.+$" />) which itself contains the value of the previous condition and the requested querystring.

If you want to be able to capture multiple conditions to reuse them in your action, you can use <conditions trackAllCaptures="true">. More information available here:

How to debug

Debugging the rewrite rules can be tricky and at time annoying…but there’s a very good tool available with the module called the Failed Request Tracing tool.
Always remember when you debug a redirect (specifically a 301) that browsers tend to cache them and that it can lead to frustration when you change the rule but nothing happens…

Rewrite outside websites

There’s one usage that’s not very well documented and that you might face one day: rewriting to an external website.
If you want to rewrite to, you can use the following rule:

<rule name="Rewrite to github">
  <match url="^code$" />
  <action type="Rewrite" url="" />

But if you try it, it will most likely not work as expected (read: it won’t show he content of It is because you need to install the Application Request Routing module and set the proxy mode to enable.