Sitecore is a complex piece of software by any measure. This series attempts to explore, demystify, and shine a light on some of the complexities involved in deploying Sitecore sites into an existing (and operational) Sitecore instance where source code is contributed by multiple parties.

The web.config file has always been a complex beast, Sitecore takes this to the next level. Sitecore needs to be everything to everyone, which means it needs to be infinitely configurable. This is great for customers but makes the configuration large, complex and fraught with danger. Lucky for us Sitecore also has a powerful configuration management framework that allows separation of configuration into 'include' files that are patched in at runtime.

The separation of these configuration files is great for multi-agency, multi-site implementations but it can also mean danger. Since the end result of all these transformations is a single Web.config (and with the includes function a single Sitecore element), developers need to be aware of the implications of making changes to the global configuration.

Use includes

Where possible it is advised to keep all configurations in the includes folder, whilst this is not always possible it makes upgrading and deploying a much easier job.

Execution order matters

Configuration files in the include folder are executed alphabetically then folders are executed (also alphabetically). As a rule you want your configurations to be patched as late as possible, this is because if you are patching into configurations from other config files you need to be sure that they have been executed so you can then patch them.

It is recommended that config files for your project are placed in their own folder within the Includes folder, this means that the default and global configuration items can be executed first.

Sometimes that is still not enough and there may be another project that has config that needs to be modified (although you really shouldn't be messing with other projects configuration), in cases like this you need to make sure your folders name is alphabetically ordered lower than the other project, sometimes this requires prefixing with an 'x'

Configurations are global, but scope them locally

Keeping in line of one of the golden rules of multi-site development, 'Don't break what works now', you should always restrict the impact of configurations to things that you are responsible for. This means, pipelines, events and other custom integrations should only impact the workflow for your items and sites.

Sometimes it is possible to scope things directly in the configuration alternatively the first line of code for global integrations should be to limit the scope based on the item context (ie to a site or base template type).

Check out the other posts in this series.

Continue reading the next in the series Keep your items tidy