Sitecore Patch Files

As anyone familiar with Sitecore’s guide of recommended practices, changing the <sitecore> section of the Web.config file directly is frowned upon.  Rather, developers should use things called Sitecore configuration include files, or patch files.  By default, these are stored in the /App_Config/Includes folder of the website.

There are plenty of blog articles about them on the internet, however there was one specific feature that seems to be relatively unknown: the set namespace.

We start off with an empty patch file:

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
               xmlns:set="http://www.sitecore.net/xmlconfig/set/">
  <sitecore>
  </sitecore>
</configuration>

Although it may be obvious to some, I’ll point out that the actual names that you use for the namespaces within the document are inconsequential: so long as the URI is correct, you can use any name you like.  The thing that you might not recognise is the second namespace declaration, and that’s what I’m going to write about.

You can use set to set an attribute of an element that already exists in the Sitecore configuration.  The attribute itself does not necessarily have to exist.  For example, the following patch file will make Sitecore do a server-side transfer for processing error pages instead of the usual 302 redirect.

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
               xmlns:set="http://www.sitecore.net/xmlconfig/set/">
  <sitecore>
    <settings>
      <setting name="RequestErrors.UseServerSideRedirect" set:value="true" />
    </settings>
  </sitecore>
</configuration>

In the above example, the name attribute does not have a set namespace, and so Sitecore will use that attribute as a predicate for matching the element.  It will then set the value attribute to "true".  You can use the same attribute for both matching and setting (as shown below); equally, you can specify multiple attributes to set.  The following example could be used to override a particular pipeline processor type:

<?xml version="1.0" encoding="utf-8" ?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"
               xmlns:set="http://www.sitecore.net/xmlconfig/set/">
  <sitecore>
    <pipelines>
      <renderField>
        <processor type="Sitecore.Pipelines.RenderField.GetLinkFieldValue, Sitecore.Kernel"
                   set:type="Foo" />
      </renderField>
    </pipelines>
  </sitecore>
</configuration>

Whenever you make a change to an include file, it’s always a good idea to ensure that it has been applied correctly.  The best and easiest way to do this is to go to /sitecore/admin/showconfig.aspx.  You’ll need to log in for security reasons, but once you’ve done that, it will present to you the Sitecore configuration after all the includes and replacements have been applied.

In Sitecore 7, the patching process seems to fail silently on syntax errors; so you need to be especially careful.  However, when a patch is successfully applied, you will see the patch:source attribute being added to the modified elements with the name of the patch file.  In Sitecore 6, if you make a syntax error in your patch file, then this will throw an error:

[NullReferenceException: Object reference not set to an instance of an object.]
   Sitecore.Diagnostics.Log.Error(String message, Exception exception, Type ownerType) +246
   Sitecore.Configuration.Factory.LoadAutoIncludeFiles(ConfigPatcher patcher, String folder) +1064
   Sitecore.Configuration.Factory.GetConfiguration() +344
   Sitecore.Diagnostics.LoggerFactory..cctor() +58

[TypeInitializationException: The type initializer for 'Sitecore.Diagnostics.LoggerFactory' threw an exception.]
...
[TypeInitializationException: The type initializer for 'Sitecore.Resources.Media.UploadWatcher' threw an exception.]
...

At first glance, it looks like a problem with the logging, but you’ll note the highlighted line in the stack trace.  The error itself doesn’t indicate which file had the problem, which can be a pain if you’ve changed multiple files.

For more general information on patch files, I’d suggest John West’s blog post, which has further links to other resources.