Sitecore web.config include files (auto-include)

The Sitecore web.config is very big. Actually, it’s so big that Sitecore have decided to split the file into several files. If you look in your /App_Config folder, you will notice a lot of .config files. All of these files (except for the ConnectionStrings.config) are actually merged into the web.config at run-time.

Sitecore also has an “auto-include” feature. Take a look at the “Include” folder. All .config files in this folder will be merged at runtime. There is some major advantages to this:

  • Seperate your own settings from Sitecore settings. You no longer has to look for your settings in the huge web.config file.
  • Deploy management. You can have seperate .config files for your development, test and production. Simply copy the appropriate files to the appropriate environment (note: We don’t use that in Pentia. We have an even smarter continous integration environment)
  • No web site restart when updating configuration. That’s right. The web site does not restart when changing settings in config files in the Include folder.

What can you do then? There is some limitations though:

  • You can only update the /configurations/sitecore section.
  • Includes are “auto-overwriting”. New elements are added. Existing elements will be overwritten.
  • You cannot delete settings.

Here is a simple file, adding 3 commands:

<configuration xmlns:patch="" xmlns:x="">
      <command name="pt:unlockall" type="PT.Locks.Commands.UnlockAll, PT.Locks" />
      <command name="pt:unlockothers" type="PT.Locks.Commands.UnlockOthers, PT.Locks" />
      <command name="pt:unlockitem" type="PT.Locks.Commands.UnlockItem, PT.Locks" />   

Inserting elements at specific position can be done using patch:before and patch:after attributes:

<configuration xmlns:patch="" xmlns:x="">
        <processor patch:after="*[@method='CheckLinks']" mode="on" type="PT.Function,PT.Library" method="MyFunction" />

Here is another example, inserting an event:

<configuration xmlns:patch="" xmlns:x="">
      <event name='item:saving'>
        <handler type="PT.PermanentRedirect.ItemSaveHandler,PT.PermanentRedirect" method="AddRedirectRecord"  />

Inserting as the first element can be done using the patch:before=’*[1]’ attribute:

<configuration xmlns:patch="" xmlns:x="">
        <processor patch:before="*[1]" mode="on" type="PT.Pipeline,PT.Code" method="AddRedirectRecord" />

You can use the ShowConfig tool located in the /sitecore/admin/ folder to see the complete merged web.config:


For further reading, see Mark Cassidy’s blog post, or read the Sitecore SDN Faq on the topic.

About briancaos

Developer at Pentia A/S since 2003. Have developed Web Applications using Sitecore Since Sitecore 4.1.
This entry was posted in Sitecore 6 and tagged , , , . Bookmark the permalink.

12 Responses to Sitecore web.config include files (auto-include)

  1. Raúl Jiménez says:

    Very well explained Brian. A minor comment, from 6.3 the app does restart when modifying an include file.


  2. Pingback: XAML (SheerUI) dialog in Sitecore 6.3.x « Brian Pedersen’s Sitecore and .NET Blog

  3. Pingback: Sitecore Include Files | TCSC Blog

  4. Pingback: Sitecore DMS uses master database per default « Brian Pedersen’s Sitecore and .NET Blog

  5. Pingback: Open Media Library from Sitecore Page Editor « Brian Pedersen’s Sitecore and .NET Blog

  6. Pingback: Open Sitecore Content Editor from the Page Editor « Brian Pedersen’s Sitecore and .NET Blog

  7. Pingback: Sitecore Custom Google Map Field | #Just Another Place To Stop By

  8. Pingback: The type initializer for ‘Sitecore.Diagnostics.LoggerFactory’ threw an exception | Sitecore basics!

  9. Pingback: Sitecore Custom Search | Learn and share

  10. Pingback: Sitecore Code Generator and O/R mapper | Brian Pedersen's Sitecore and .NET Blog

  11. Pingback: Sitecore Advanced Configuration in .config files | Brian Pedersen's Sitecore and .NET Blog

  12. Pingback: Which of my old Sitecore posts are still valid in Sitecore 9? | Brian Pedersen's Sitecore and .NET Blog

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.