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:

<configuration>

  <nodes configfile="web.config">

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

    <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"/>

    </node>

  </nodes>

</configuration>

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

path - 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:








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:




name - Used to specify an attribute only when action is removeattribute or updateattribute

value - Used to specify the value for an attribute only when action is updateattribute

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

References

• The manifest file
  

To be Continued . . .