Use a patch file to customize the Sitecore configuration

Current version: 10.0

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

This topic describes how to:

Create a patch file

To create a patch file to customize configuration settings:

Create a file in one of the two customizable layers in Sitecore:
- The Custom layer – you must place patch files that customize default Sitecore settings in a way that is independent of the system environment in the /App_Config/Include folder, which belongs to the Custom layer.
- The Environment layer – you must place patch files that configure Sitecore for a specific environment, such as QA or Development, in the /App_Config/Environment folder, which belongs to the Environment layer.
You can place the file either in the root of the folder or in a subfolder that you create within the folder.
Give the patch file a name ending with the extension .config.

Start with this basic structure in the file:

RequestResponse

<?xml version="1.0" encoding="utf-8"?>
<configuration>
<sitecore>
</sitecore>
</configuration>

In the <sitecore> section of the patch file, add the setting changes that you want to add to the configuration.

Note

You can only patch settings in the app_config/sitecore.config file. Settings in other files such as the web.config and app_config/layers.config files cannot be patched. If you need to change the settings in these files, you must edit them directly.

Use rule-based configuration to control the conditions under which Sitecore applies the patched settings.

Control how settings are applied

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 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. We therefore strongly recommend 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.

To control how Sitecore inserts elements:

Register the patch and set XML namespaces that enable you to use attributes to modify or add settings, by adding them to the <configuration> setting:
RequestResponse
```
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" 
xmlns:set="http://www.sitecore.net/xmlconfig/set/">
```
Use a patch: attribute to specify where the element is placed relative to existing elements, or to specify that it replaces or updates 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.
- patch:delete – removes the specified element.
- patch:instead – replaces the specified element.
For example, to add a site named mysite and place it before the existing site with the name website, use the following syntax:
RequestResponse
```
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/">
  <sitecore>
    <sites>
      <site patch:before=”*[@name='website']” name=”mysite” ... />
    </sites>
  </sitecore>
</configuration>
```

Note

You can use examples of patch files to help you change the Sitecore configuration. You can also find a more detailed description of patch files in the Include File Patching Facilities guide. Be aware that this description relates primarily to Sitecore version 6.

Control the load order of configuration files

The order in which Sitecore loads configuration files is important because the changes that a file makes can be modified or overwritten by files that load later. If Sitecore finds the same configuration setting in multiple files, the last file to load overwrites the previous versions of the setting.

To control the sequence in which the configuration files load within a layer:

In the /App_config/layers.config file, add a <loadOrder> setting to the layer's definition:
RequestResponse
```
<layer name="Custom" includeFolder="/App_Config/Custom/">
<loadOrder>
</loadOrder>
</layer>
```

Add the file folders or individual files inside the <loadOrder> section in the order you want them to load:

RequestResponse

<loadOrder>
<add path="Folder23" type="Folder" />
<add path="Folder9/sitespecific.config" type="File" />
<add path="Folder1" type="Folder" />
</loadOrder>

When Sitecore encounters a <loadOrder> setting, it loads the configuration files in this order:

Folders and files that are specified in the <loadOrder> section load first, in the order they are listed. In the previous example, the files in the Folder23 folder load first, then the sitespecific.config file, and then the files in the Folder1 folder.
Folders and files that are not specified in the <loadOrder> section load second. They load in alphabetical order. Files that are placed in the root of a folder load before files within subfolders.

Note

You can use the Show Config tool to see the resulting configuration as it looks when Sitecore compiles it at runtime. You can also use the Show Config tool to simulate changing the configuration rules or disabling configuration layers without actually changing the configuration.

Do you have some feedback for us?

If you have suggestions for improving this article,