Control a patch file setting

Abstract

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.