XML Update Reference

Product version:	EPiServer CMS 5 R2 SP1
Document version:	1.0
Document last saved:

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 (e.g. web.config) via the Update-EPiXmlFile cmdlet located in the EPiServer.Install.Common.1 PowerShell snap-in.

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:
<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 doesn't 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":
<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. __fistChild is a boolean attribute indicating that the element should be added as the first child element. The default is false. The add element may be specified instead as an alternative to setAttribute.
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.
<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.

<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 with the release of EPiServer CMS 5.2 SP1. 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 item. Here you should see a list of XSD’s. Click on the Add button and locate the XMLUpdate.xsd file. Finally, click the OK button to close the XML Schemas dialog. You should now get intellisense support for the EPiServer XML Update schema.