Configuration patch file examples

Abstract

Examples of how to write patch files that add or change server configuration settings.

The following examples of patch syntax illustrate how patching affects Sitecore 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 Sitecore configuration, you can use these examples of patch syntax to help you add or change configuration settings in Sitecore.

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 type test2, 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 type test2, 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 site mysite, and 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>