Configuring XML Update Reference (CMS 7)

Note: This topic has no later version.

Introduction

The EPiServer deployment system has rudimentary support for manipulation of xml files in a transactional manner. The primary target for XML manipulation is the ASP.NET web.config file, but there should be no problem manipulating other XML files as well. The XML modification support is based on an xml file consisting of manipulation commands in the form of XML elements and attributes. These commands are then applied to a target xml file (for example, web.config) via the Update-EPiXmlFile commandlet located in the EPiServer.Install.Common.1 PowerShell snap-in.

Structure of an XML Update File

The Update-EPiXmlFile commandlet requires that all commands in the xml update file are located as children to a common root node. The name of the root node is not important, simply choose something illustrative like “commands” or “modifications”. The order of the commands is important as they will be executed sequentially in the order they are listed.

XML

 <?xml version="1.0" encoding="utf-8"?>
  <commands>
   <remove ... />
    <setAttribute ... />
    <addAttribute ... />
    <addBlock ... >
     ...
    </addBlock>
   ...
</commands>

Commands

The following commands are currently supported:

Remove

XML Node Type	Name	Description
Element	remove	The remove element is used for removing elements or attributes from the target xml document.
Attribute	path	An XPath expression identifying the XML Node to remove.

Example: The following example will remove the SqlServer role provider from web.config:

XML

<remove path="/configuration/system.web/roleManager/providers/add[@name = 
            'SqlServerRoleProvider']"/>

Set Attribute

XML Node Type	Name	Description
Element	setAttribute	Used to unconditionally set a new attribute value. The attribute will be created if it does not already exist. The set element may be specified instead as an alternative to setAttribute.
Element	set	Short name for setAttribute.
Attribute	path	An XPath expression identifying the parent element of the attribute to set.
Attribute	attributeName	Name of the attribute to set.
Attribute	attributeValue	The new attribute value to set.

Example: The following example will set the debug attribute on the compilation element to true:

XML

<setAttribute path="/configuration/system.web/compilation" 
            attributeName="debug" attributeValue="true"/>

Add Attribute

XML Node Type	Name	Description
Element	addAttribute	addAttribute has the same parameters and functionality as setAttribute with the difference that addAttribute will not update existing attribute values.
Attribute	path	An XPath expression identifying the parent element of the attribute to add.
Attribute	attributeName	Name of the attribute to add.
Attribute	attributeValue	The attribute value to set.

Add / Merge XML Block

XML Node Type	Name	Description
Element	addBlock	The addBlock element is used for adding or merging XML elements within existing elements in the target document. The elements to merge into the target xml document are added as children to the addBlock element in the modification document. There are two special attributes that can be added to each element beneath the addBlock element. __keyAttributes is a comma separated list of attribute names. When the XML blocks are merged, attribute values of the named attributes are used to identify existing elements in the target document corresponding elements in the source block. If an element with matching attribute values are found in the target document the element will be updated, otherwise a new element will be added. __firstChild is a boolean attribute indficating that the element should be added as the first child element. The default is false. Note that if you use __firstChild="true" without specifying any __keyAttributes the first child element of the matching type will be overwritten. The add element may be specified instead as an alternative to addBlock.
Element	add	Short name for addBlock.
Attribute	path	An XPath expression identifying the node where the XML data will be added or merged. If any part of the path cannot be found then the modification is not made.

Example: The following XML block will add or update entries in the appSettings section of web.config. If elements with the same value in the key attribute exists the value attributes are updated, otherwise new elements are added.

XML

<addBlock path="/configuration">
 <appSettings>
    <add key="companyName" value="EPiServer" __keyAttributes="key" />
    <add key="country" value="sweden" __keyAttributes="key" 
            __firstChild="true" />
  </appSettings>
</addBlock>

Note that the following XML block will only be added if the appSettings section already exists.

XML

 <addBlock path="/configuration/appSettings">
    <add key="companyName" value="EPiServer" __keyAttributes="key" />
    <add key="country" value="sweden" __keyAttributes="key" 
            __firstChild="true" />
</addBlock>

Schema

An XML Schema file (XMLUpdate.xsd) is available in EPiServer CMS 5.2 SP1 and later releases. The file is installed in the <Program Files>\EPiServer\Shared\Install\Xsd folder. To use this in Visual Studio 2008, open the xml document and then select the XML > Schemas menu to see a list of XSDs. Click the Add button, locate the XMLUpdate.xsd file and click the OK button to close the XML Schemas dialog. You should now get intellisense support for the EPiServer XML Update schema.