Michael Washington in a blog about updating his sites made reference to the fact that you no longer need to manualy modify your web.config settings prior to upgrading a site.

Why is this?  The answer is a new class that was introduced into the core (in 4.6.0) called XmlMerge.  This class is designed to allow developers to create xml files that can be used to "update" one of the core "config" files, and is especially useful for upgrades or component installations.

We have had the ability for some time to provide cleanup files - these files are named xx.xx.xx.txt and contain a list of folders and files to delete when upgrading to version xx.xx.xx.  This allows us to remove unneccessary files from production sites.  Starting in version 4.6.0 we added the ability to add a "xx.xx.xx.config" file which contained the changes required to "upgrade" a core config file.

Rather than try and explain - lets look at an example. The 4.6.0.config file:

<configuration>
    <nodes configfile="web.config">
        <node path="/configuration/system.web/httpModules" action="update" key="name" collision="overwrite">
            <add name="Compression" type="DotNetNuke.HttpModules.Compression.CompressionModule, DotNetNuke.HttpModules" />
            <add name="RequestFilter" type="DotNetNuke.HttpModules.RequestFilter.RequestFilterModule, DotNetNuke.HttpModules" />
            <add name="UrlRewrite" type="DotNetNuke.HttpModules.UrlRewriteModule, DotNetNuke.HttpModules" />
            <add name="Exception" type="DotNetNuke.HttpModules.Exceptions.ExceptionModule, DotNetNuke.HttpModules" />
            <add name="UsersOnline" type="DotNetNuke.HttpModules.UsersOnline.UsersOnlineModule, DotNetNuke.HttpModules" />
            <add name="DNNMembership" type="DotNetNuke.HttpModules.Membership.MembershipModule, DotNetNuke.HttpModules" />
            <add name="Personalization" type="DotNetNuke.HttpModules.Personalization.PersonalizationModule, DotNetNuke.HttpModules" />
        </node>
        <node path="/configuration/dotnetnuke/friendlyUrl/providers" action="update" key="name" collision="overwrite">
            <add name="DNNFriendlyUrl"
                 type="DotNetNuke.Services.Url.FriendlyUrl.DNNFriendlyUrlProvider, DotNetNuke.HttpModules"
                 includePageName="true"
                 regexMatch="[^a-zA-Z0-9 _-]" />
        </node>
    </nodes>
</configuration>

In version 4.6 - the HttpModules were all merged into a single assembly - the web.config file therefore needed to be updated to reflect this.  In this config file - there are two "node" elements which are the building blocks of the XmlMerge file.  The attributes tell the XmlMerge class how to deal with the content inside the node. 

So for the first node we have:

• path="/configuration/system.web/httpModules" - this is an Xpath path that identifies the node being modified in the target file - in this case the "httpModules" element in the system.web element of the configuration
• action="update" - this is the action - in this case the existing element is being "updated"
• key="name"  - this is the key to use - in this case "name" - the XmlMerge class will identify the child nodes to change by matching the name attribute "Compression", "Exception etc.
• collision="overwrite" - this is the behaviour to use if the child node exists - in this case the old entry will be overwritten by the new one

The target file is "web.config" as identified by the configfile attribute on the outer nodes element.

In addition to using this in the core Installer/Upgrader - the new "Universal Extension Installer" supports this ability too.  Again - as an example lets look at a fragment of a manifest from the new installer.

                    <config>
                        <configFile>web.config</configFile>
                        <install>
                            <configuration>
                                <nodes>
                                    <node path="/configuration/dotnetnuke/caching/providers" action="update" key="name" collision="overwrite">
                                        <add name="BroadcastPollingCachingProvider"
                                             type="DotNetNuke.Services.Cache.BroadcastPollingCachingProvider.BPCachingProvider, DotNetNuke.Caching.BroadcastPollingCachingProvider"
                                             providerPath="~\Providers\CachingProviders\BroadcastPollingCachingProvider\" />
                                    </node>
                                </nodes>
                            </configuration>
                        </install>
                        <uninstall>
                            <configuration>
                                <nodes>
                                    <node path="/configuration/dotnetnuke/caching/providers/add[@name='BroadcastPollingCachingProvider']" action="remove" />
                                </nodes>
                            </configuration>
                        </uninstall>
                    </config>

In this example (part of the manifest for installing the BroadcastPollingCachingProvider) you can see that the manifest defines a "config" element - which tells the Installer that we are "updating" a config file.  It has two separate sections that correspond to the same basic structure as the XmlMerge file above, one for installing the provider - with a similar set of attributes, and one for uninstalling, which shows how you would remove a section of the config file.

A full description of the API is beyond the scope of this blog, but if you want to start learning how to use this in your own modules/extensions - I would suggest that you look for the "XmlMerge.vb" file in the DotNetNuke project - the main entry points are the "UpdateConfig" methods.