Umbraco web.config rule of thumb on URL Rewrite

  • Sunday, February 22, 2015 9:05 PM EST
  • Last Edited: Sunday, February 22, 2015 9:57 PM EST

There are two methods of setting up URL rewrite in umbraco. The first way is by placing all the rewrites in web.config. Second approach is by writing all the rules in UrlRewriting.config. The advantage of the first approach is if you are very comfortable with ASP.Net Rewrite rules, you do not need to do conform to Umbraco's url rewrite syntax. This doesn't mean Umbraco's syntax is hard to learn. It is very easy. In fact, I would place all my rewrite rules in there to clean up my web.config file. But in my case, I work with a client who is very familiar with the first approach so with the website I am working on, some rules are written in UrlRewriting.config while others are in web.config.

We came across this error where the rewrites in web.config were not working. After spending a lot of time debugging, I have written this rule on how to do the rewrites going forward:

Rule of thumb is if the folder exists but umbraco doesn’t know about its existence, place it under urlrewriting.config. Otherwise, if the folder doesn’t exist or it is a reserved path, redirect should work.

By reserved path I mean the umbracoReservedPaths attribute in web.config. This attribute is used to prevent pages being parsed by Umbraco. (source:

To test out, I first created these rules in web.config:

//doesn’t work. The folder /Images/ exists but is not a reserved path in umbraco. To resolve,you need to write the rule in urlrewriting.config 
<rule name="type 1" stopProcessing="true">
<match url="^Images/index.html$" />
<action type="Redirect" url="" />

//works. The folder /reservedpath/ exists and is a reserved path in umbraco. To register a reserved path add in umbracoReservedPaths in web.config
<rule name="type 2" stopProcessing="true">
<match url="^reservedpath/index.html$" />
<action type="Redirect" url="" />

//works. The folder /Scripts/ exists and is not a reserved folder. But it is included during installation. This is a reserved path for umbraco
<rule name="type 3" stopProcessing="true">
<match url="^Scripts/index.html$" />
<action type="Redirect" url="" />

//works. The folder/page does not exist.
<rule name="type 4" stopProcessing="true">
<match url="^ASDF/index.html$" />
<action type="Redirect" url="" />

//doesn’t work. The folder /pdf/ exists but is not a reserved folder in umbraco. To resolve,you need to write the rule in urlrewriting.config
<rule name="type 5" stopProcessing="true">
<match url="^pdf/index.html$" />
<action type="Redirect" url="" />

//works. The folder/page. doesn't exist.
<rule name="type 6" stopProcessing="true">
<match url="^redirectsuccess/index.html$" />
<action type="Redirect" url="" />

To create a url rewrite rule in umbraco, use this guideline in this url


comments powered by Disqus