Learn More





DNN Community Blog

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.

DotNetNuke Tips and Tricks #19: Leveraging XML Merge Scripts

As long-time DotNetNuke users well know, DotNetNuke contains an extensive API that makes the platform extremely powerful and flexible.  Over time the core APIs have continued to expand as new features were added and existing features were enhanced.  One of the core APIs which has been part of DotNetNuke since 4.6 was released three years ago today is the XML Merge API.

The XML Merge API was developed to enable developers to define changes that need to occur to any xml based file within the website.  It is primarily used by the core framework to make updates to web.config but has utility beyond just updating web.config.  Web.config management was a huge problem in early versions of DotNetNuke.  Managing and applying the web.config changes every time you upgraded DotNetNuke was a time-consuming and error-prone process.  The XML Merge API was developed in part to address this need.

When I first created the API, I needed a way to merge dozens of custom URL rewriter rules into the siteurls.config for the AspDotNetStorefront module.  These rules could change with new versions of the ASPDNSF module and so I also needed to support the ability to apply these changes in a version specific manner.  My first version was included as part of the ASPDNSF module, but due to a contractual arrangement, I was able to make this API available in DotNetNuke as well.


Since the very beginning, DotNetNuke has supported the ability to apply versioned SQL scripts to the database.  The XML Merge API extended this concept to the system configuration files.  Similar to the XX.XX.XX.SqlDataProvider files, the core uses a series of XX.XX.XX.config files in the Install/Config folder within the DotNetNuke website.  Each merge script defines an atomic set of changes that will occur for upgrades to a specific DotNetNuke version.  As the upgrade process steps through each version in the upgrade chain, it applies the associated sqldataprovider scripts as well as the associated config merge scripts.

One extremely useful core script is the Net35.config script which makes the necessary changes to the web.config file to upgrade a site from ASP.Net 2.0 to ASP.Net 3.5.  If you look at the Net35 merge script, you will find that there are a couple dozen changes that are needed to web.config to make the transition from 2.0 to 3.5.  I have had to add these changes manually to a user’s site on more than one occasion and it is not a fun task.

Unfortunately we are finding situations where the merge scripts may not actually execute properly.  If the administrator has locked down changes to web.config or if they have added changes to web.config which fundamentally changes the XML structure, then it is possible that the scripts won’t be executed.  In those situations the user is not left with any option beyond hand editing, which as I previously pointed out is a very tedious process for any significant change.

One useful feature that exists in DotNetNuke is the ability to manually execute SQLDataProvider scripts using the Host/SQL page.  This module allows you to load an existing SQL script, edit the script and apply it to your database.  If a SQLDataProvider script doesn’t work during an upgrade you have the option to easily apply this script manually to your site.  If you need to test SQL scripts for your modules during development to make sure they will work properly, you can use the SQL page to handle that task as well.


I thought it would be great if we had a page that performed a similar function for XML Merge scripts.  Not being one to wait for others to create the feature I coded one up for myself.  I wanted the new module to have all of the same basic features as the SQL module and the result is pretty close.  The UI can use a little tweaking, but all of the needed functionality is present.


The module was actually pretty easy to implement since it is really just calling the core framework.  A simple event handler to take care uploading the file:

Protected Sub cmdUpload_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles cmdUpload.Click
    If IsValidDocType(uplMergeScript.PostedFile.ContentType) Then
        Dim scriptFile As New System.IO.StreamReader(uplMergeScript.PostedFile.InputStream)
        txtMerge.Text = scriptFile.ReadToEnd
    End If
End Sub


and a simple event handler to execute the script when the “Execute Merge” link button is pressed:

Protected Sub cmdExecute_Click(ByVal sender As Object, ByVal e As System.EventArgs) Handles cmdExecute.Click
    If IsValidXmlMergDocument(txtMerge.Text) Then
            Dim doc As New System.Xml.XmlDocument()
            Dim merge As New DotNetNuke.Services.Installer.XmlMerge(doc, "", "")
        Catch ex As Exception
            Skins.Skin.AddModuleMessage(Me, Localization.GetString("ERROR_Merge", Me.LocalResourceFile), ModuleMessage.ModuleMessageType.RedError)
        End Try
    End If
End Sub


That’s really all there is to it.  I have packaged up the module and added it to the DotNetNuke forge.  I hope to get it incorporated into the upcoming DotNetNuke 5.6 release which should be out later this fall, but in the meantime feel free to download the module and use it on your own sites.


Comment Form

Only registered users may post comments.


2sic Daniel Mettler (124)
Aderson Oliveira (15)
Alec Whittington (11)
Alex Shirley (10)
Andrew Nurse (30)
Anthony Glenwright (5)
Antonio Chagoury (28)
Ash Prasad (22)
Ben Schmidt (1)
Benjamin Hermann (25)
Benoit Sarton (9)
Beth Firebaugh (12)
Bill Walker (36)
Bob Kruger (5)
Brian Dukes (2)
Brice Snow (1)
Bruce Chapman (20)
Bryan Andrews (1)
cathal connolly (55)
Charles Nurse (163)
Chris Hammond (203)
Chris Paterra (55)
Clinton Patterson (28)
Cuong Dang (21)
Daniel Bartholomew (2)
Dave Buckner (2)
David Poindexter (3)
David Rodriguez (2)
Doug Howell (11)
Erik van Ballegoij (30)
Ernst Peter Tamminga (74)
Geoff Barlow (6)
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 (270)
John Mitchell (1)
Jon Henning (14)
Jonathan Sheely (4)
Jordan Coopersmith (1)
Joseph Craig (2)
Kan Ma (1)
Keivan Beigi (3)
Ken Grierson (10)
Kevin Schreiner (6)
Leigh Pointer (31)
Lorraine Young (60)
Malik Khan (1)
Matthias Schlomann (15)
Mauricio Márquez (5)
Michael Doxsey (7)
Michael Tobisch (3)
Michael Washington (202)
Mike Horton (19)
Mitchel Sellers (28)
Nathan Rover (3)
Navin V Nagiah (14)
Néstor Sánchez (31)
Nik Kalyani (14)
Peter Donker (52)
Philip Beadle (135)
Philipp Becker (4)
Richard Dumas (22)
Robert J Collins (5)
Roger Selwyn (8)
Ruben Lopez (1)
Ryan Martinez (1)
Salar Golestanian (4)
Sanjay Mehrotra (9)
Scott McCulloch (1)
Scott S (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)
Timo Breumelhof (24)
Tony Henrich (3)
Torsten Weggen (2)
Vicenç Masanas (27)
Vincent Nguyen (3)
Vitaly Kozadayev (6)
Will Morgenweck (37)
Will Strohl (163)
William Severance (5)
Try Evoq
For Free
Start Free Trial
a Demo
See Evoq Live
Need More Information?