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. | |||
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.