Manage Your Sitecore Config Files Like a Boss

Posted on May 04, 2016 in Technical  | No comments

Author: Ben Lai Date: 04/05/2016

The Start

Whilst Sitecore is a robust platform for your CMS needs, when it comes to the issue of managing config files, unfortunately not much guidance exists to help you organise these files in an easy and logical way. This isa shame, given the importance of config files within a Sitecore instance. 

Inevitably, many Sitecore instances end up with config files that become a real pain point for everyone involved when issue resolution becomes difficult, as a result of their initial setup.

Lex - Reality

This doesn't need to be your reality!

Sitecore actually offers decent management options with regard to configuration files, particularly within the <sitecore> settings subsection. Since the release of Sitecore 7, the entire directory structure under /App_Config/Include gets merged into the final configuration file, and this provides a lot of scope for introducing easy, logical source control options to your project.

Setting the Scene

We recently had a situation where it was necessary for us to manage multiple agencies who all required personalised config files in order to run the various parts of a client’s single Sitecore instance. This necessitated re-organising how the config files were laid out to allow for easier maintenance when it came to incorporating the myriad of configurations from the different agencies.

Getting it Done

First of all, we wanted to extract all possible configurations from the default web.config to give us easy access to each part, without having to scroll through the entirety of what used to be an admittedly large default web.config in Sitecore.


Take note of the config sections defined at the top, and edit after them to reflect something similar to:

  <connectionStrings configSource="App_Config\ConnectionStrings.config" />
  <appSettings configSource="App_Config\AppSettings.config" />
  <sitecore configSource="App_Config\Sitecore.config" />
  <log4net configSource="App_Config\Log4net.config"/>

This will allow you to extract each of the above sections into their own files (if they weren’t already there) in App_Config, and reduce the amount of clutter in the web.config.


In addition to the above adjustments, we grouped up the various config files in /App_Config/Include/ into folders:

         Config files folders

All the standard config files provided went into the first directory, any platform specific configs (environment adjustments for Int/Staging/Production, etc) into the second, and the last two were for the various configs provided by external agencies. The numbering of the folders meant that the agency configs would be processed last and not be overwritten by the default ones.

We also maintained a specific version numbered naming scheme for the agency configs to ensure that they would load in the specific order required, and that older configs would not accidentally overwrite newer ones.

The Specifics

Writing patch files for Sitecore configurations is fairly straightforward. 

Question no question

Adding a Variable

  1. Create a config file name specific to the functionality of the addition
  2. Start the config file with a node like:
    <?xml version="1.0" encoding="utf-8" ?>
    <configuration xmlns:patch="">
  3. Determine what setting you wish to add, and its location in the node tree
If necessary, narrow down the specific node by including unique attributes in parent nodes, e.g.
		<agent type="Sitecore.Tasks.UrlAgent">

Then, you can add in your node using the patch keyword, which offers a few options:
  • patch:before: Insert the element before the specified element.
  • patch:after: Insert the element after the specified element.
  • patch:instead: Replace the specified element.
  • patch:delete: Remove the specified element.
  • patch:attribute: Define or replace the specified attribute.

For example, adding another site would result in a node like:

			<site patch:before="*[@name='website']"
				name="XXXXX" virtualFolder="/site" physicalFolder="/site" 
				startItem="/home" language="en" contentLanguage="en"
				database="web" domain="extranet" disableClientData="false" 
				cacheHtml="true" htmlCacheSize="250MB" 
				renderingParametersCacheSize="100MB" allowDebug="true" 
				enablePreview="true" enableWebEdit="true" enableDebugger="true" 
				enableAnalytics="true" notFoundItem="/sitecore/content/newsite/Home"

Which will add in your new site node before the “website” node already defined in Sitecore.config.

- You can also replace with patch:instead

	<agent type="Sitecore.Tasks.UrlAgent">
		<LogActivity patch:instead="LogActivity[0]">false</LogActivity>

- Remove nodes with patch:delete

		<processor type="Sitecore.Pipelines.Initialize.PrecompileSpeakViews, Sitecore.Speak.Client">
			<patch:delete />
		<processor type="Sitecore.Pipelines.Initialize.PrecompileSpeakViews, Sitecore.Speak.Client">
			<patch:delete />

- Edit attributes with patch:attribute

Replacing an Attribute

While patch:attribute is available, we find set:value to be easier to parse. For that, you have to adjust the namespace at the top of the file to also include: 


After which, you can then edit with:

<sc.variable name="dataFolder"    set:value="E:\inetpub\" />

General Points

We encouraged the other agencies to label their more generic config adjustments with unique keys related to their agency names and versions to ensure that any patching that occurred would only affect their own specific keys. If this was not adhered to, it would often end up that a patch would accidentally change some other agency’s configuration.

/sitecore/admin/ShowConfig.aspx is a tool that is perfect for managing this sort of configuration, as now it also indicates which specific config file made an adjustment, so it is much easier to track down errors and correct them.


The configuration management Sitecore offers is extremely flexible, and the tools offered really do allow for fairly easy and logical maintenance of the system. Having individual patch files makes multi-agency configs both possible and maintainable in source control, bringing a high level of sanity and accountability to your project.

Feel Great