Using patch files to customize the Sitecore configuration

Last updated Monday, May 1, 2017 in Sitecore Experience Platform for Administrator
Keywords: Configuration

You use patch files to add or change configuration settings in Sitecore. Sitecore merges the patch files with the Sitecore.config file to create the configuration file that is used at runtime.

This topic describes:

Patch file placement

You must place patch files in the /App_Config/Include folder of the Sitecore installation, either directly or in a subfolder. You must give the patch files names ending with the extension.config.

Sitecore merges patch files in alphabetical order. Files within a folder are merged before files in subfolders within the folder. For example, the file /App_Config/Include/mywebsite9.config is merged before the file /App_Config/Include/Myfolder/mywebsite1.config.

If Sitecore finds the same configuration in multiple patch files, the last patch file to be merged overwrites the previous versions of the configuration.

For example, if all the files in the following list define the same configuration, Sitecore only uses the configuration from the last file listed:

  • /App_Config/Include/z.config
  • /App_Config/Include/b/b.config
  • /App_Config/Include/b/c.config
  • /App_Config/Include/c/a.config [used]

Patch file syntax

The following XML namespaces contain all the attributes and elements related to patching:

  • Patch – http://www.sitecore.net/xmlconfig/
  • Set – http://www.sitecore.net/xmlconfig/set/

You must declare the namespaces before you can use them in a patch file. Normally, you declare them at the beginning of the file:

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

When Sitecore applies the changes from a patch file, it tries to match each element in the patch file to an element in the existing configuration. It matches elements using the combination of the element name and all the attributes of the element. If there is a match, Sitecore updates the existing element. If there is no match, Sitecore inserts a new element.

Note

If a patch file element matches more than one element in the existing configuration, Sitecore applies the update to the first matching element that it finds. It is therefore strongly recommended that you specify enough attributes of the element to uniquely identify it.

By default, Sitecore inserts new elements at the end of the configuration section that the elements belong to. You can use a patch: attribute in an element to specify where it is placed relative to existing elements, or to specify that it replaces, updates, or deletes an existing element of the same name. You can use the following attributes:

  • patch:before – inserts the element before the specified element.
  • patch:after – inserts the element after the specified element.
  • patch:attribute – defines or replaces the specified attribute of the element. You can achieve the same effect using the set namespace.

For example, to add a site before the site with the name website, use the following syntax:

<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <sites>
      <site patch:before=”*[@name='website']” name=”mysite” ... />
    </sites>
  </sitecore>
</configuration>

You can use examples of patch files to help you change the Sitecore configuration.

Note

In the /App_Config/Include folder, there are several files ending with the extension .example. In these files, you can see examples of how to patch configuration elements. To include an example file in the runtime configuration, you must rename the file to end in .config.

You can find a more detailed description of patch files on the Sitecore Developer Network site. Note that this description relates primarily to Sitecore version 6.

Previewing the result of patching

To see the configuration file that is used at runtime, you load the URL http://<hostName>/sitecore/admin/showconfig.aspx.

You can also use the Config Builder in the Sitecore Instance Manager to simulate the merging process. The Config Builder merges all patch files with the Sitecore.config file and enables you to save the resulting file anywhere you like. You can then check whether your configuration changes have been patched in as expected.

You can find the Config Builder under Bundled Tools on the Home tab in the Sitecore Instance Manager. You must select a Sitecore site before you can select the Config Builder.

Note

The resulting configuration file shows where patched elements come from. For example, an element that was taken from the Sitecore.Analytics.config file includes the patch:source="Sitecore.Analytics.config" attribute.

Send feedback about the documentation to docsite@sitecore.net.