How Sitecore Config Files Load

Thursday, March 10, 2016

How Sitecore Config Files Load

By: Scott Gillis, Lead Consultant – Starting with Sitecore 7.5, you may have noticed that the App_Config \ Include directory was getting larger and larger and even started to include sub-directories. So what is developer or admin to do with all these new files.

In my clean install of Sitecore Experience Manager 8.1 - Update 1 with Web Forms for Marketers (WFFM) and Email Experience Manager (EXM) modules, I was looking at nearly 140 files, some of which may be disabled but are still there cluttering up the file system. This was before adding any custom patch files I needed for my own code base and functions.

On one hand, I'm glad that Sitecore has had the foresight to pull as much into configuration files as possible as it allows us as implementers the ability to fine-tune solutions, but it does create a bit of a headache when a) I can’t find a setting that I know exists and b) just want to insert at a certain point but my xpath query doesn't seem to want to take effect.

My Go-To for Managing the Headache

So, the first thing we need is a tool to help us manage all of these. I’ve found that the free Visual Studio Code has become the best tool for sorting through and managing these files. Why?

Well, for starters, it allows me to load an entire directory into tree view for file selection, and even provides syntax highlighting which is always helpful when staring down a lengthy Sitecore configuration file.

Image One - How Sitecore Config Files Load

The feature that fully sold me on it as my go-to configuration file tool is the deep file search it provides. Clicking the magnifying glass icon, will provide you the ability to do text or regex search of all the files you’ve loaded. It shows counts of how many times in that file the term/expression is found, and a snippet of where it is, so you can quickly identify if that was the one you wanted.

Image Three - How Sitecore Config Files Load

Load Order

Understanding how Sitecore loads and combines configuration files is critical to make sure, when overriding or inserting via patch commands, what you are looking for has already been loaded or it just won't be added.

My research and testing has shown the following load order.

Image Two - How Sitecore Config Files Load

  1. Web.config
    • Any 'Config Source' attributes are loaded at this time
  2. App_Config Files
    • Files inside App_Config are loaded alphabetically
  3. App_Config\Include Files
    • All files in Include are loaded alphabetically
  4. App_Config\Include Directories
    • All directories are loaded alphabetically
    • Contents of each directory are loaded alphabetically
  5. App_Config\Prefetch
    • All files in Prefetch are loaded alphabetically
  6. App_Config\Security
    • All files in Security are loaded alphabetically

After some testing and reading others findings, I've concluded the following best practice needs to be taken into consideration when managing configuration files starting with Sitecore 7.5, but applies just as well to past versions too.

Because of the alphabetical loading and the fact that directories are loaded last, you will want to create a custom directory call 'zz.CustomConfigurations' or something similar to ensure that it and it's contents are loaded last. My recommendation is to use the double 'z' prefix to ensure that you are always last and any Marketplace Modules don't cut you out from being last.

I will note that, as of Sitecore Experience Platform 8 update 6 and Sitecore Experience Platform 8.1 update 1, Sitecore is including a Z.SwitchMasterToWeb directory in App_Config \ Include. Its only file at this time is the Switch Master to Web configuration file, but is a helpful example of why this is required.

Why would you want to add these extra steps to your configuration file management? First, I find that it helps new developers and admins easily identify what files are custom, thus it is easy to know what configurations should be committed into source. Second, by requiring your files to be loaded last, the x path used in the patch attributes will be sure to find what they are looking for. Sadly, if the patch x-path query is incorrect or finds nothing, there is no error indicator in the log and you only find out when things start to break or end up not working.

Until commenting gets implemented, feel free to tweet me questions or comments @thecodeattic or on Sitecore Slack Community as @gillissm. I would be happy to discuss Sitecore configuration files in further detail and ways to make them more manageable for all of us.