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" />

43 thoughts on “Storing URL rewrite mappings in a separate file”

  1. 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.

  2. 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?

  3. hi
    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

  4. Ruslany,

    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!

  5. 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

  6. Hi

    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

  7. 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!

  8. 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.

  9. 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!

  10. 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,

  11. 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!

  12. hi,
    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.


  13. 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

  14. 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.

  15. 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!


  16. 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

  17. 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?

  18. Hi,

    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??????????

  19. 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! 😉

  20. 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!!

  21. 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

  22. 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 )

  23. 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.

  24. 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.

  25. 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

  26. Hi,

    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

  27. 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?


  28. In case if your rewrite.config file also tend to exceed the 250kb bench mark, is it possible to split rewrites to multiple configSource files?

Leave a Reply

Your email address will not be published. Required fields are marked *