1. Use a patch file to customize the Sitecore configuration

Configuration patch file examples

Version:

The following examples of patch syntax illustrate how patching affects configuration. All examples show the original configuration, then the patch files, and finally the configuration after the patch files have been merged with the Sitecore.config file.

The examples illustrate:

To customize your configuration, you can use these examples of patch syntax to help you add or change configuration settings.

To use the patch and set namespaces, declare them at the beginning of the patch file as part of the <configuration> setting:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" 
xmlns:set="http://www.sitecore.net/xmlconfig/set/">
    <sitecore>
        . . . . . 
    </sitecore>
</configuration>

Merging configurations

Configurations from different patch files are merged in the order the patch files are processed.

<!-- Sitecore.config -->
<settings>
  <setting name="name" value="Aaron" />
</settings>
<!-- /App_Config/Include/file1.config -->
<settings>
  <setting name="city" value="New York" />
</settings>
<!-- /App_Config/Include/file2.config -->
<settings>
  <setting name="country" value="USA" />
</settings>

The configuration used at runtime is:

<settings>
  <setting name="name" value="Aaron" />
  <setting name="city" value="New York" />
  <setting name="country" value="USA" />
</settings>

Inserting an element before a specific element

You can insert a configuration element before a specific element. This example adds a processor before the processor with the test2 type, regardless of the position of test2 in the configuration:

<!-- Sitecore.config -->
<test>
  <processor type="test1" />
  <processor type="test2" />
  <processor type="test3" />
</test>
<!-- Patch file -->
<test>
  <processor type="testA" patch:before = "processor[@type='test2']"/>
</test>

The configuration used at runtime is:

<test>
  <processor type="test1" />
  <processor type="testA" />
  <processor type="test2" />
  <processor type="test3" />
</test>

Inserting an element after a specific element

You can insert a configuration element after a specific existing element. This example inserts a processor after the processor with the test2 type, regardless of the position of test2 in the configuration:

<!-- Sitecore.config -->
<test>
  <processor type="test1" />
  <processor type="test2" />
  <processor type="test3" />
</test>
<!-- Patch file -->
<test>
  <processor type="testA" patch:after = "processor[@type='test2']"/>
</test>

The configuration used at runtime is:

<test>
  <processor type="test1" />
  <processor type="test2" />
  <processor type="testA" />
  <processor type="test3" />
</test>

Adding or updating an attribute

You can add a new attribute or update the value of an existing attribute. If the attribute already exists, its existing value is replaced by the value from the patch file. If the attribute does not already exist in mysite, it is added to mysite. You can use either the patch namespace or the set namespace to achieve this effect.

This example adds the domainPath attribute to the mysite site, sets it to /home, and changes the virtualFolder attribute to /sitecore modules/web:

<!-- Sitecore.config -->
<sites>
  <site name="mysite" virtualFolder="/"></site>
</sites>

This patch file uses the patch namespace to change the attributes:

<!-- Patch file -->
<sites>
    <site name="mysite" virtualFolder="/">
        <patch:attribute name="domainPath">/home</patch:attribute>
        <patch:attribute name="virtualFolder">/sitecore modules/web</patch:attribute>
    </site>
</sites>

This patch file uses the set namespace to achieve the same result:

<!-- Patch file -->
<sites>
    <site name="mysite" virtualFolder="/" set:domainPath="/home" set:virtualFolder="/sitecore modules/web"></site>
</sites>

The final result is the same for both patch files. The configuration used at runtime is:

<sites>
  <site name="mysite" domainPath="/home" virtualFolder="/sitecore modules/web"></site>
</sites>

Deleting an element

You can delete a configuration element using patch:delete. Specify the name attribute for the element node in order to identify the element to remove.

Important

Take care when using patch:delete because it removes the specified element and all its attributes from the configuration at runtime.

For example, this is the given Sitecore config:

<!-- Sitecore config -->
<sitecore>
    <element name="a"/>
    <element name="b"/>
    <element name="c"/>
</sitecore>

The corresponding patch config deletes element "b":

<!-- Patch file -->
<sitecore>
    <element name="b">
        <patch:delete />
    </element>
</sitecore>

The configuration used at runtime is:

<sitecore>
    <element name="a"/>
    <element name="c"/>
</sitecore>

If the element doesn't have a name attribute, you can list the element to remove and all its attributes, and include the patch:delete element. For example, this is the configuration file:

<sitecore>
  <element type="example" value="foo" />
  <element type="example" value="bar" />
</sitecore>

And this is the corresponding patch file:

<?xml version="1.0" encoding="utf-8"?>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <element type="example" value="foo">
      <patch:delete />
    </element>
  </sitecore>
</configuration>

The resulting configuration at runtime is:

<sitecore>
  <element type="example" value="bar" />
</sitecore>

Replacing the value of an element

Use the patch:instead attribute to specify that the selected element should be inserted instead of a sibling element. Unlike patch:before and patch:after, this attribute allows you to completely replace the original node or element.

The syntax is:

<processor type="CustomC, CustomA" patch:instead="*[@type='Sc, Sc']" />

<!-- Sitecore.config -->
<sitecore>
    <element name="a"/>
    <element name="b"/>
    <element name="c"/>
</sitecore>
<-- Patch file -->
<sitecore>
    <element name="d" patch:instead="*[@name='b']"/>
</sitecore>

The configuration used at runtime is:

<sitecore>
    <element name="a"/>
    <element name="d"/>
    <element name="c"/>
</sitecore>
If you have suggestions for improving this article, let us know!