Use a patch file to customize the Sitecore configuration
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/Includefolder, 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/Environmentfolder, 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
Start with this basic structure in the file:RequestResponsexml
<?xml version="1.0" encoding="utf-8"?> <configuration> <sitecore> </sitecore> </configuration>
<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.configfile. Settings in other files such as the
app_config/layers.configfiles 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.
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:
setXML namespaces that enable you to use attributes to modify or add settings, by adding them to the
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/" xmlns:set="http://www.sitecore.net/xmlconfig/set/">
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
patch:delete– removes the specified element.
patch:instead– replaces the specified element.
For example, to add a site named
mysiteand place it before the existing site with the name
website, use the following syntax:RequestResponsexml
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <sites> <site patch:before=”*[@name='website']” name=”mysite” ... /> </sites> </sitecore> </configuration>
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.configfile, add a
<loadOrder>setting to the layer's definition:RequestResponseshell
<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:RequestResponseshell
<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.configfile, 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.
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.