Storing URL rewrite mappings in a separate file

When using rewrite maps in IIS URL Rewrite it is very common to have a very large number of entries in a rewrite map. In order to avoid cluttering the configuration file - web.config - with this configuration data the rewrite maps can be defined in a separate configuration file. That file can then be referenced from the web.config file. This post provides an example of how this can be done.

Create a file called rewritemaps.config in the same directory where web.config file is. Open that file in notepad and add the following:

  <rewriteMap name="Redirects">
    <add key="/oldurl" value="/newurl" />
    <add key="/otheroldurl" value="/othernewurl" />

Save this file and then open web.config file in notepad. In the web.config file add the following inside of the <rewrite> section:

<rewriteMaps configSource="rewritemaps.config" />

The configSource attribute tells IIS configuration that the <rewriteMaps> section is defined in a separate file rewritemaps.config. This referenced section can be now uses as if it was defined in the same web.config file. Also, the IIS Manager UI will work well with this referenced file: when you modify or add entries to the rewrite map they will be stored in the rewritemaps.config file.

Here is a complete example web.config file that uses the rewrite map from referenced configuration file:

    <rewriteMaps configSource="rewritemaps.config"><rewriteMaps>
      <rule name="Redirect rule1 for Redirects">
        <match url=".*" />
          <add input="{Redirects:{REQUEST_URI}}" pattern="(.+)" />
        <action type="Redirect" url="{C:1}" appendQueryString="false" />

The same approach can be used for storing rewrite rules in a separate configuration file, e.g.:

<rules configSource="rewriteRules.config" />


ruslany on May 19th 2010 in URLRewrite

PoorFairAverageGoodExcellent (6 votes, average: 3.50 out of 5)

41 Responses to “Storing URL rewrite mappings in a separate file”

  1. Gravatar ImageAJ responded on 21 May 2010 at 12:43 pm #

    Does this also apply to applicationHost.config rules for server level rewrites?

  2. Gravatar Imageruslany responded on 21 May 2010 at 4:03 pm #

    This does not apply to applicationHost.config. It only works with web.config files.

    Also, note that if you manually edit rewritemaps.config file by using a text editor then the changes to the file will not take effect until you recycle the IIS application pool. But if you modify the rewrite map entries by using IIS Manager UI then the changes will take effect right away.

  3. Gravatar Imageruslany responded on 04 Jun 2010 at 4:18 pm #

    Useful information: the maximum allowed size of web.config file by default is 250Kb (100Kb in Vista).

    The default can be changed by setting a registry key HKLM\SOFTWARE\Microsoft\InetStp\Configuration\MaxWebConfigFileSizeInKB (REG_DWORD)

    More information on this and other registry keys can be found at List of registry keys affecting IIS7 behavior

  4. Gravatar Imager4ds responded on 29 Jun 2010 at 10:50 am #

    Is it possible to have a different set of URL rewrite rules on the same domain? For example might have one set of rules, while might have another or add to the already existing rules?

  5. Gravatar ImageFB responded on 13 Jul 2010 at 4:11 am #

    can we have the 301 redirects stored as a separate file too? if yes, how?


  6. Gravatar Imagenk responded on 23 Jul 2010 at 12:02 am #

    this is my url link
    herbal.aspx?link=rejuvenating butea.txt&id=8&h=butea

    - i want like this

    herbal/butea/rejuvenating butea
    can you pl guide me to do. i m very new to iis 7

    thank you

  7. Gravatar Imagebryan responded on 22 Sep 2010 at 8:50 pm #


    I need to set up a ton of URL re-directs, We consumed an old web site but need to set up about 1000 re-directs. We have the mapping of old to new URL’s done, but we need to configure the rule or alias file. I do not know how to really do this effectivley. The Rules UI will not work for this many. Typically we did this in apache inside the httpd.conf file similar to a plain jane etc/hosts. It was very easy to maintain and didn’t require re-boots. Is there way to accomplish any easier in IIS 7.5 than installing the re-write module and input configuration to each URL to and from?

    Is there a simple list I can dump to map to?

    ‘Obi-rus’ your my only hope… :-)

    Thanks for your help in advanced!

  8. Gravatar ImageEdgar responded on 05 Oct 2010 at 10:33 am #

    Then, if I copy the htaccess file into the same path where web.config is, and modify , my mode rewrite used into my php application will work?

    Well, I really don’t know about how to activate the mode rewrite into a IIS server to use Apache use the mode rewrite for PHP applications

  9. Gravatar Imageruslany responded on 05 Oct 2010 at 11:46 pm #

    @bryan: This article may help.

    @Edgar: Have you tried importing the rules from .htaccess file as described here?

  10. Gravatar ImageBiker Man responded on 27 May 2011 at 5:34 am #


    I am trying to set this up with iis7 and so I am adding in the line to the web.config as

    and then in the referenced file it look like this

    but the site errors. Is my structure incorrect on this as I am looking to make dynamic redirects and so this would be perfect if I could get is working

  11. Gravatar ImageJacob Coens responded on 31 May 2011 at 4:42 am #

    Hi Ruslany,

    I’m developing a ASP.NET User Control that provides a Web User Interface for managing a rewrite map. On my development environment, changes to the mappings file are picked up immediately by Url Rewrite, but on my test environment this does not happen until the application pool has been recycled. I’m guessing this is a caching-issue. Could you point me in the right direction? I think I should somehow clear the Url Rewrite cache after making modifications to the rewrite mappings file, but I can’t seem to find out how.

    In an earlier comment, you say: “Also, note that if you manually edit rewritemaps.config file by using a text editor then the changes to the file will not take effect until you recycle the IIS application pool. But if you modify the rewrite map entries by using IIS Manager UI then the changes will take effect right away.”

    Could you explain how the IIS Manager UI for Url Rewrite does this?

    Thanks in advance!

  12. Gravatar Imageruslany responded on 06 Jun 2011 at 2:44 pm #

    Hi Jacob, I believe IIS Manager UI touches the corresponding web.config file when rules in rewritemap.config files are changed. This causes IIS to reload the configuration.

  13. Gravatar ImageJacob Coens responded on 10 Jun 2011 at 7:41 am #


    Thank you for your reply, so there was no magic coding involved on your behalf :-)
    I’ll let you know if it works.

  14. Gravatar ImageJacob Coens responded on 23 Jun 2011 at 5:48 am #

    Touching web.config works, although this means that I will have to make sure that the identity associated to the application pool has the appropriate rights to change the properties of the web.config file.
    By keeping the rewrite map in a separate file I hoped to have worked around this requirement, but unfortunately there is no way around it.
    Thanks again!

  15. Gravatar ImageTim Doscher responded on 23 Jun 2011 at 11:13 pm #

    Hi Ruslany,

    We are trying to get rewrite maps working on iis 7.5 and don’t seem to be having any luck. Do you know of any good steps for troubleshooting this feature? We are using the 2.0 url rewrite tool from microsoft.

    Thank you,

  16. Gravatar Imageruslany responded on 24 Jun 2011 at 10:03 am #

    Hi Tim,

    This would be a place to start: Using rewrite maps. To troubleshoot the feature you can use Failed Request Tracing.

  17. Gravatar ImageJM responded on 08 Dec 2011 at 3:11 pm #

    I followed your examples (found on this page and those similar examples found on and the rewrites worked with the rewrite map, except that my CSS wasn’t working. Once I added the following condition, it worked “”. Is this because my css file was being captured by the rule?

    Your articles are extremely helpful (I have used many as reference). Thanks again!

  18. Gravatar ImageJM responded on 08 Dec 2011 at 3:12 pm #

    Sorry, i tried to encode the xml…
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true"/>

  19. Gravatar ImageAnkush responded on 29 Dec 2011 at 4:20 am #

    i am doing the redirect using rewritemap.config concept which is acessed by web config , the size of rewritemap.config is around 3.3 mb but i am facing 500.52 error in the website instead if i reduce the size of rewritemap.config to 50 kb it works fine could please you tell me how to configure for file of size 3.3 ,mb i have allready tried changing registry value but it is not helping.


  20. Gravatar ImageJames Moberg responded on 09 Jan 2012 at 8:27 am #

    Your sample web.config file has invalid XML.

    Change line #4 to:

  21. Gravatar ImageRajendra responded on 10 Jan 2012 at 11:34 pm #

    Hi Ruslany,
    We are using SDL tridion cms package for a new website.
    We have a requirement where the user can provide user friendly urls while creating a page in Tridion.
    Is there any built in functionality in tridion which can handle both the url and the internal links on page.
    Presently we have come up with two approaches
    1. using IIS url rewrite module and providing an external xml file(this file will be updated automatically when a user added a new page.)
    2. using httpmodule

    In both the cases whenever there is a change in the input file (for eg. if the user creates a new page, a new entry will be added to the xml file) the IIS or the application need to be restarted to reflect the changes.
    Is there any other way in which we dont need to restart the server?
    P.S. there is no fix pattern of url and there fore we cannot define regex rules.
    Rajendra Dhaundiyal

  22. Gravatar ImageJdk responded on 16 Sep 2012 at 6:27 am #

    Hi Ruslany – I am facing an issue with importing the rules file.
    Some background info: We have a web server where there are two web sites, default and one for Team Foundation server which is on port 8080. There have been mutiple rules defined at IIS root level (not at default website or TFS web site).

    I added one more web server to leverage high availability thru Hardware based load balacing. I want similar kind of rules on second server also. I copied these rules from existing server.
    I am facing two issues
    1. When I open “URL Rewrite” at IIS root level, there is no “Import” option.
    2, When I try at Default WebSite level (because my eventual goal is to redirect from port 80 to port 8080) and getting “The data in the page is invalid. Correct the data and try again.”
    here is my rules file:

    Please suggest.
    Thanks in adavnace.

  23. Gravatar ImageIndumathi responded on 03 May 2013 at 5:41 am #

  24. Gravatar Imagehari.sadu responded on 02 Jul 2013 at 12:21 am #

    can rewritemap be written in applicationhost.config?
    Thanks for the reply.

  25. Gravatar Imagejl responded on 27 Sep 2013 at 5:04 am #

    configSource: element is not declared

  26. Gravatar ImageJohn Hu responded on 06 Jan 2014 at 9:07 am #

    Hi ruslany,

    I have a couple questions hoping you can help.

    1. I know there is 250 kb size limit for web.config. Is there any limit for rewriterules.config and rewritemaps.config? We currently put all rules in rewriterules.config that reaches 250 kb but need to add much more soon, so want to make sure.

    2. Is it ok to user both rewriterules.config and rewritemaps.config for the same site? Others already put quite amount of static and non-static redirects all in rewriterules.config. Now if I put new static redirects in rewritemaps.config, would they all work along? Does IIS walk through rewriterules.config first, then go through rewritemaps.config?

    Thank you in advance!


  27. Gravatar ImageRobert Pate responded on 23 May 2014 at 12:23 pm #

    To answer John Hu’s questions:

    I’ve just tested your first question. The same 250 KB limit for that exists for web.config also exists for RewriteMaps.config. It can be increased as Ruslan mentioned. This is the error: Cannot read configuration file because it exceeds the maximum file size

    To avoid making the registry change, I tried using two different RewriteMaps source files. It doesn’t work. This is the error I get:
    Config section 'system.webServer/rewrite/rewriteMaps' already defined. Sections must only appear once per config file. See the help topic <location> for exception

    To answer your 2nd question, yes, I’m also using a mix of both RewriteRules.config and RewriteMaps.config. They work fine together. The module only pulls from the “Maps” file when directed to by a rule in the “Rules” file.

    I figure John Hu has already figured this out, but wanted to post in case other people had similar questions.

    Robert Pate

  28. Gravatar ImageAkash responded on 01 Jun 2014 at 12:32 am #

    Can we use multiple configuation files as

    something like that?

  29. Gravatar ImageLaMaze Johnson responded on 02 Jun 2014 at 2:46 pm #

    I previously used a tool called ISAPI_Rewrite for IIS6 that allowed you to store several different rewrite maps in individual files and link to their location on the file system from within the config file.

    Does iis rewrite allow for more than one file for all the mapping data?

  30. Gravatar ImagePhani responded on 10 Jul 2014 at 8:29 am #


    I’m getting Specified configSource cannot be parsed while trying to try rewrite Maps

    In web.config I place,

    and in root file of my published code I placed “rewritemaps.config” and write the following,

    when I’m placing the above code in web.config its working fine. But when I’m trying to place the code in another file, I’m getting error

    Any suggestions??????????

  31. Gravatar Imagedax responded on 24 Oct 2014 at 3:49 am #

    Dear Ruslany,

    Firstly, let me thank you on the great blog and and knowledge that you are sharing with others. I have followed this article and created rewrite map. It is working (Yeey!!) but I get HTTP Error 404.0 – Not Found error because there aren’t folders / files on file system where the rule redirected me.

    I need to create another rule for rewrite so I was hoping that you can help me. :)

    I tried with this rule but is not working:


    Thank you! ;)

  32. Gravatar ImageSam responded on 28 Nov 2014 at 7:19 am #

    Hi, I have tried the above, as I have over 1500 explict rewrites to do (I already have around 100 in the current config file) when I impleamented the above, I just got a 500 error :(

    Would it be because I left some rules in the config? so was conflicting between the two? or could some of my syntax be wrong in the Imported rules?

    Any help / light would be a massive help! THANKS!!

  33. Gravatar Imagelee elkins responded on 09 Mar 2015 at 1:38 pm #

    this works like a charm for IIS 7.5
    HKLM\SOFTWARE\Microsoft\InetStp\Configuration\MaxWebConfigFileSizeInKB (REG_DWORD)

    but now I’ve moved to server 2012 RS with IIS 8.5 and get the file size too big error error again even after apllying the above change. Any ideas?? THANKS

  34. Gravatar ImageShilpa responded on 08 Apr 2015 at 1:51 am #

    Redirects can be split into 2 different files and then referenced into the web.config so that the web.config is not cluttered.

    The rewritemaps.config can be used to write static redirects and the rewriterules.config can be used to add redirects that have any regex rules, although static redirects can also be added in the rules file. The rewritemaps redirects are then called from the rules file.

    so in the web.config, the following needs to be added

    Ensure both rewritemaps.config and rewriterules.config are in the same folder hosting the web.config
    The rewrite maps will have entries as below

    All rules within rewritemaps can then be called by a single rule in the rewriterules.config as below

    This way you can have 2 files having redirects (so a total of 500kb at your disposal )

  35. Gravatar ImageJohn responded on 10 Nov 2015 at 11:42 am #

    Hi, the post by Shilpa on 08 April 2015 is just what I need to do, giving me 500k of redirects in 2 files – any chance of seeing the sample code which has been left out? I can’t find anywhere else on the interweb offering any other solution for the 250k file size rewrite limit.

  36. Gravatar ImageSJNBham responded on 17 Nov 2015 at 9:02 pm #

    The closing rewriteMaps tag needs a “/” I think. When I tried to use the code snippet, IIS Manger complained it was valid XML until I added it. Might want to update your sample code above.

  37. Gravatar ImageHiren responded on 06 Jul 2016 at 10:38 am #

    hi ,

    I have more than 10,000 old urls need to redirect what is best way ?

    Website contains many products and each have different url like query string is changes

  38. Gravatar ImageAmit responded on 07 Dec 2016 at 1:28 pm #


    Is it possible to break rewritemap.config file down in multiple files?
    I am running into file size issue.

    Config Error: Cannot read configuration file because it exceeds the maximum file size

    Or have multiple files similar to rewritemap.config included in web.config?

    Thanks in advance

  39. Gravatar ImageJono responded on 17 Nov 2017 at 1:33 am #

    Hey Ruslan,

    Wondering if you’ve encountered this issue within a Azure Web App filesystem, where you dont have access to the Registry to increase the rewriteRules.config max file size?


  40. Gravatar Imageruslany responded on 21 Nov 2017 at 11:15 am #

    Hi Jono, unfortunately it is not possible to access and modify registry on the VM where Azure Web App runs.

  41. Gravatar ImageAlo responded on 22 Dec 2017 at 6:12 am #


    To be able to use url rewrite mappings in an azure web app, do I need to enable “Enable proxy functionality in ARR” as stated in your following article:

    Or can I just add them to web.config without any additional configuration and expect it to work?

    Thanks in advance.

Trackback URI | Comments RSS

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

XML Markup: If You want to add XML code to the comment please XML encode it first, otherwise the code will not show up.

Recently Published Articles