Control a patch file setting
How to control whether a patched setting is merged with an existing setting or added as a new setting.
When you use patch files to change the Sitecore configuration, you must identify the node you want to add or update. By default, Sitecore updates existing nodes with the patched attributes, but you can use significant attributes to force Sitecore to add new nodes instead.
This topic explains how to:
Specify a node
You must specify which node you want to update.
To specify the node:
Specify the element name and its place in the XML structure in the
Sitecore.config
file.
For example, the AliasActive
setting is part of the <settings>
element node, which is part of the <sitecore>
element node. To change the value of the AliasActive
setting to false you must include these element nodes in the patch file:
<sitecore> <settings> <setting name="AliasActive"> <patch:attribute name="value">False</patch:attribute> </setting> </settings> </sitecore>
Use a significant attribute
When Sitecore processes attributes from patch files, it looks for existing nodes in the Sitecore.config
file that fit the attributes in the patch file node. If it finds one, by default, it merges the attributes in the patch file with the existing node.
For example, you can have two patch files that both add a script file to the <clientscripts>
node in the Sitecore.config
file:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <clientscripts> <script src="script-1.js" language="javascript" /> </clientscripts> </sitecore> </configuration>
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <clientscripts> <script src="script-2.js" language="javascript" att1="test" /> </clientscripts> </sitecore> </configuration>
When Sitecore processes the first patch file, it adds the <script src="script-1.js">
element. When it processes the second patch file, it merges the new information with the first <script>
element, updating the src
attribute and adding the att1
attribute. The final result is:
<sitecore> <clientscripts> <script src="script-2.js" language="javascript" att1="test" patch:source="Add-script-2.config" /> </clientscripts> </sitecore>
If you want to add the node from the second patch file as a new node, you can add a significant attribute to the node definition. Sitecore never merges significant attributes, so if the second script
element includes a significant attribute with a unique value, Sitecore adds it as a new element. For example, you can add a desc
attribute to the script
element in the second patch file:
<configuration xmlns:patch="http://www.sitecore.net/xmlconfig/"> <sitecore> <clientscripts> <script src="script-2.js" language="javascript" att1="test" desc="new script" /> </clientscripts> </sitecore> </configuration>
The result after processing both patch files is now:
<sitecore> <clientscripts> <script src="script-1.js" language="javascript" patch:source="Add-script-1.config" /> <script desc="new script" src="script-2.js" language="javascript" att1="test" patch:source="Add-script-2.config" /> </clientscripts> </sitecore>
You can use the following significant attributes in this way:
ancestor
assembly
builderType
category
channelId
comment
contains
creationType
desc
description
displayName
extensions
facetKey
fieldId
fieldName
fieldType
fieldTypeName
file
find
folder
groupName
hint
hostname
id
implementationType
innerText
interface
key
messageDataType
messageItemBaseType
method
name
namespace
networkName
originalKey
path
postingConfiguration
prefix
providerName
querystring
ref
region
serviceType
sitecoreKey
statusCode
tagName
templateId
trafficType
trigger
type
typeConverter
typeName
uid
urlReferrerHost
value
verb
viewName
with
xmlControl
xmlns
To change the value of a significant attribute in an existing node:
Use the patch:attribute syntax:
<sitecore> <clientscript > <script src="script-1.js" att1="test"> <patch:attribute name="desc">new description</patch:attribute> </script> </clientscript> </sitecore>
Add a significant attribute definition
If you cannot use any of the default significant attributes, you can define your own.
To define your own significant attribute:
Add the significant attribute to the
Sitecore.config
file, within the<sitecore>
element node.
For example, the following adds a significant attribute called my-own-attribute
:
<patch> <significantAttributes> <add name="my-own-attribute"/> </significantAttributes> </patch>
Important
Sitecore processes its list of significant attributes before it processes the patch files. You must therefore add new significant attributes directly to the Sitecore.config
file and you cannot add them through a patch file. Only use this method if you absolutely cannot use any of the predefined attributes.