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.