Sitecore & The Last Include
Sitecore provides you with a method of applying changes to Sitecore configuration in the web.config, without modifying the web.config itself.
You do this by creating separate .config files and putting them in the /App_Config/Include folder.
Sitecore loads these include files during initialization and merges it with the web.config.
It also offers custom XML attributes to gain control over the way that include files are merged, by "patching" elements and attributes.
The goal of this blog post is not to describe how you use configuration includes.
John West has already described that in more detail in this blog post: All about Web.config include files with the Sitecore ASP.NET CMS.
I just want to point out the fact that configuration files are included in alphabetical order.
This is very important to know, because otherwise you may try to modify parts of the configuration that have not been included yet.
Imagine that you have this configuration stored in /App_Config/Include/SomeConfigFile.config:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <settings> <setting name="NewSitecoreSetting" value="some_value" /> </settings> </sitecore> <configuration>
And you try to patch that setting with your own /App_Config/Include/MyConfigFile.config include file:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <settings> <setting name="NewSitecoreSetting"> <patch:attribute name="value">my_new_value</patch:attribute> </setting> </settings> </sitecore> <configuration>
This will not work, because SomeConfigFile.config is included after MyConfigFile.config.
So the NewSitecoreSetting setting doesn't exist yet when you try to modify it in MyConfigFile.config.
When you are implementing a Sitecore solution, you usually want to make sure that your custom configuration is included at the very last moment.
That enables you to modify any existing configuration and guarantees that no other include files will modify your own configuration.
The solution (or workaround, really)
Having looked at the code that is responsible for loading the configuration includes, I noticed that it includes files from sub folders as well.
More specifically, it includes all the files first and then starts including files from sub folders!
This works in our advantage as we can now create one sub folder for our custom configuration and be sure that its contents is the last to be included.
My implementations now have an /App_Config/Include/Custom folder that contains the include files for my solution.
As long as you don't add any more sub folders, you can be sure that your /App_Config/Include/Custom includes are loaded at the very last moment, allowing you to manipulate all the existing Sitecore configuration while knowing for sure that your own configuration will stay untouched!
It's still just a workaround though and I've put in a feature request for a way of controlling the order in which configuration files are included.
Something like adding an patch:include-order="100" attribute to the <configuration> node in each include file.
Hopefully we will see this improved in future versions!