The XML Merge API (DotNetNuke.Services.Installer.XmlMerge), first introduced in DotNetNuke version 4.06.00, is used for updating XML based documents, such as web.config, using an XML based syntax. Thanks to the XML Merge API, it is not only unnecessary but ill-advised to manually modify an existing site's web.config file during an upgrade from versions 4.06.02 onward.
The XML Merge API is called during installation and upgrade of the DotNetNuke framework to make version specific modifications to web.config and is also called during the installation/uninstallation of extensions (particularly providers) when processing a version 5 extension manifest (.dnn file) which includes a Config Component
Here's a simple example extracted from the file \Install\Config\05.05.00.config contained in the packages for DotNetNuke v 5.05.00:
<node path="/configuration/system.web/httpHandlers" action="update" key="path" collision="overwrite">
<add verb="*" path="Telerik.RadUploadProgressHandler.ashx" type="Telerik.Web.UI.Upload.RadUploadProgressHandler, Telerik.Web.UI"/>
<node path="/configuration/system.webServer/handlers" action="update" key="name" collision="overwrite">
<add name="RadProgressHandler" verb="*" path="Telerik.RadUploadProgressHandler.ashx" type="Telerik.Web.UI.Upload.RadUploadProgressHandler, Telerik.Web.UI" preCondition="integratedMode"/>
When processed during an install/upgrade of DotNetNuke v 5.05.00, this configuration source file instructs the XML Merge API to add or update the <configuration><system.web><httpHandlers> and/or the <configuration><system.webServer><handlers> section of web.config to properly reference the Telerik RadUploadProgress HTTP handler.
The configuration source file must include properly structured xml and consists of a root <configuration> node containing a <nodes> collection. Notice that the target xml file which will be modified is specified by the configfile attribute whose value will be a root relative filepath. Most typically the target file is "web.config".
Each of the <node> sections contained within the nodes collection will be structured to apply one or a series of adjacent modifications to a section, node, or attribute of the target configuration file. Each <node> element may receive the following attributes, some of which are required in combination and some of which are mutually exclusive:
<node> Attributespath -
Specifies the section, node or attribute which will be targeted for modification using standard XML Xpath syntax. An node having a specific attribute value may be targeted using a construction such as @name='dotnetnuke'action -
Specifies the action which will be performed on the target or to a node relative to the target. The following values may be supplied for the action attribute:
add - Adds the node following the target node. If the target node is a collection, the node is added as the last element of the collection.
insertbefore - Inserts the node before the target node.
insertafter - Inserts the node after the target node.
remove - Removes the target node and its inner content
removeattribute - Removes a specific attribute/value pair from the target node.
update - Updates a node
updateattribute - Updates or adds a specific attribute/value pair on the target node.targetpath -
When processing an update action defines a new target based on an XPath that is the value of a named attribute on the original target specified by the path attribute. In other words a relative target. See example below.key -
When processing an update action may be used to specify a child node of the target node that will be modified based on the value of the attribute name (key) that is contained in the source configuration node's immediate child node. Note that targetpath and key are mutually exclusive attributes.collision -
Defines what action will be taken if the node or attribute to be added or updated already exists. The following values may be supplied for the collision attribute:
ignore - No changes will be made to the target configuration file.
overwrite - The existing node or attribute is overwritten by the modification.
save - Xml comment markers will be inserted around the existing node and the new or updated node will be inserted in the same location in the document tree.name -
Used to specify an attribute only when action is removeattribute or updateattributevalue -
Used to specify the value for an attribute only when action is updateattributenameSpace
and nameSpacePrefix -
Adds the given namespace and/or namespace prefix to the target configuration file's namespace table and uses the XmlNamespace Manager to locate the target node by a namespace qualified path. I have to research this usage more fully in the XmlMerge API code and in the few examples which I found.
To be Continued . . .