New Community Website

Ordinarily, you'd be at the right spot, but we've recently launched a brand new community website... For the community, by the community.

Yay... Take Me to the Community!

The Community Blog is a personal opinion of community members and by no means the official standpoint of DNN Corp or DNN Platform. This is a place to express personal thoughts about DNNPlatform, the community and its ecosystem. Do you have useful information that you would like to share with the DNN Community in a featured article or blog? If so, please contact .

The use of the Community Blog is covered by our Community Blog Guidelines - please read before commenting or posting.

XmlMerge - what is it?

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:

    <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 path="/configuration/dotnetnuke/friendlyUrl/providers" action="update" key="name" collision="overwrite">
            <add name="DNNFriendlyUrl"
                 type="DotNetNuke.Services.Url.FriendlyUrl.DNNFriendlyUrlProvider, DotNetNuke.HttpModules"
                 regexMatch="[^a-zA-Z0-9 _-]" />

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.

                                    <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 path="/configuration/dotnetnuke/caching/providers/add[@name='BroadcastPollingCachingProvider']" action="remove" />

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.



Comment Form

Only registered users may post comments.


Aderson Oliveira (22)
Alec Whittington (11)
Alessandra Davies (3)
Alex Shirley (10)
Andrew Hoefling (3)
Andrew Nurse (30)
Andy Tryba (1)
Anthony Glenwright (5)
Antonio Chagoury (28)
Ash Prasad (37)
Ben Schmidt (1)
Benjamin Hermann (25)
Benoit Sarton (9)
Beth Firebaugh (12)
Bill Walker (36)
Bob Kruger (5)
Bogdan Litescu (1)
Brian Dukes (2)
Brice Snow (1)
Bruce Chapman (20)
Bryan Andrews (1)
cathal connolly (55)
Charles Nurse (163)
Chris Hammond (213)
Chris Paterra (55)
Clint Patterson (108)
Cuong Dang (21)
Daniel Bartholomew (2)
Daniel Mettler (181)
Daniel Valadas (48)
Dave Buckner (2)
David Poindexter (12)
David Rodriguez (3)
Dennis Shiao (1)
Doug Howell (11)
Erik van Ballegoij (30)
Ernst Peter Tamminga (80)
Francisco Perez Andres (17)
Geoff Barlow (12)
George Alatrash (12)
Gifford Watkins (3)
Gilles Le Pigocher (3)
Ian Robinson (7)
Israel Martinez (17)
Jan Blomquist (2)
Jan Jonas (3)
Jaspreet Bhatia (1)
Jenni Merrifield (6)
Joe Brinkman (274)
John Mitchell (1)
Jon Henning (14)
Jonathan Sheely (4)
Jordan Coopersmith (1)
Joseph Craig (2)
Kan Ma (1)
Keivan Beigi (3)
Kelly Ford (4)
Ken Grierson (10)
Kevin Schreiner (6)
Leigh Pointer (31)
Lorraine Young (60)
Malik Khan (1)
Matt Rutledge (2)
Matthias Schlomann (16)
Mauricio Márquez (5)
Michael Doxsey (7)
Michael Tobisch (3)
Michael Washington (202)
Miguel Gatmaytan (3)
Mike Horton (19)
Mitchel Sellers (40)
Nathan Rover (3)
Navin V Nagiah (14)
Néstor Sánchez (31)
Nik Kalyani (14)
Oliver Hine (1)
Patricio F. Salinas (1)
Patrick Ryan (1)
Peter Donker (54)
Philip Beadle (135)
Philipp Becker (4)
Richard Dumas (22)
Robert J Collins (5)
Roger Selwyn (8)
Ruben Lopez (1)
Ryan Martinez (1)
Sacha Trauwaen (1)
Salar Golestanian (4)
Sanjay Mehrotra (9)
Scott McCulloch (1)
Scott Schlesier (11)
Scott Wilkinson (3)
Scott Willhite (97)
Sebastian Leupold (80)
Shaun Walker (237)
Shawn Mehaffie (17)
Stefan Cullmann (12)
Stefan Kamphuis (12)
Steve Fabian (31)
Steven Fisher (1)
Timo Breumelhof (24)
Tony Henrich (3)
Torsten Weggen (3)
Tycho de Waard (4)
Vicenç Masanas (27)
Vincent Nguyen (3)
Vitaly Kozadayev (6)
Will Morgenweck (40)
Will Strohl (180)
William Severance (5)
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out
What is Liquid Content?
Find Out