Use a patch file to customize the Sitecore configuration

You use patch files to add or change configuration settings in the Sitecore.config file. XM Cloud 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 :
- The Custom layer – you must place patch files that customize default XM Cloud settings in a way that is independent of the system environment in the <project root>/src/platform/App_Config/Include/ folder, which belongs to the Custom layer.
- The Environment layer – you must place patch files that configure XM Cloud for a specific environment, such as QA or Development, in the <project root>/src/platform/App_Config/Environment folder, which belongs to the Environment layer.
Make sure the App_Config and relevant layer directories (Include or Environment), and any custom configuration files, are explicitly included in the project in the development environment you are using, such as Visual Studio.
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.

Control how settings are applied

When XM Cloud 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, XM Cloud updates the existing element. If there is no match, XM Cloud inserts a new element.

Note

If a patch file element matches more than one element in the existing configuration, XM Cloud 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, XM Cloud inserts new elements at the end of the configuration section that the elements belong to.

To control how XM Cloud 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 XM Cloud configuration.

Control the load order of configuration files

The order in which XM Cloud loads configuration files is important because the changes that a file makes can be modified or overwritten by files that load later. If XM Cloud 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 XM Cloud 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.

Do you have some feedback for us?

If you have suggestions for improving this article,