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="http://www.sitecore.net/xmlconfig/" xmlns:x="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <commands>
      <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" />   
    </commands>
  </sitecore>
</configuration>

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

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

Here is another example, inserting an event:

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

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

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:x="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <pipelines>
      <uiDragItemTo>
        <processor patch:before="*[1]" mode="on" type="PT.Pipeline,PT.Code" method="AddRedirectRecord" />
      </uiDragItemTo>
     </processors>
  </sitecore>
</configuration>

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

http://[yourwebsite]/sitecore/admin/showconfig.aspx

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