This blog was originally posted on my dotnetnuke.com Blog. It has been updated and edited.
Michael Washington in a blog about updating his DotNetNuke sites made reference to the fact that you no longer need to manually 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 DotNetNuke version 4.6.0) called XmlMerge. This class is designed to allow developers to create xml files that can be used to "update" one or more of the core "config" files, and is especially useful for upgrades and component installations.
We have had the ability for some time to provide file-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 unnecessary 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:
Listing 1: 04.06.00.config file |
1: <configuration>
2: <nodes configfile="web.config">
3: <node path="/configuration/system.web/httpModules" action="update" key="name"
collision="overwrite">
4: <add name="Compression" type="DotNetNuke.HttpModules.Compression.CompressionModule,
DotNetNuke.HttpModules" />
5: <add name="RequestFilter" type="DotNetNuke.HttpModules.RequestFilter.RequestFilterModule,
DotNetNuke.HttpModules" />
6: <add name="UrlRewrite" type="DotNetNuke.HttpModules.UrlRewriteModule,
DotNetNuke.HttpModules" />
7: <add name="Exception" type="DotNetNuke.HttpModules.Exceptions.ExceptionModule,
DotNetNuke.HttpModules" />
8: <add name="UsersOnline" type="DotNetNuke.HttpModules.UsersOnline.UsersOnlineModule,
DotNetNuke.HttpModules" />
9: <add name="DNNMembership" type="DotNetNuke.HttpModules.Membership.MembershipModule,
DotNetNuke.HttpModules" />
10: <add name="Personalization"
type="DotNetNuke.HttpModules.Personalization.PersonalizationModule,
DotNetNuke.HttpModules" />
11: </node>
12: <node path="/configuration/dotnetnuke/friendlyUrl/providers" action="update" key="name"
collision="overwrite">
13: <add name="DNNFriendlyUrl"
14: type="DotNetNuke.Services.Url.FriendlyUrl.DNNFriendlyUrlProvider,
DotNetNuke.HttpModules"
15: includePageName="true"
16: regexMatch="[^a-zA-Z0-9 _-]" />
17: </node>
18: </nodes>
19: </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". Other values for action are add, insertbefore, insertafter, remove, removeattribute, updateattribute.
- 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.
Note - in this scenario if the end user has added additional HttpModules these are unaffected by the "merge" - only the named child nodes are replaced.
During the install/upgrade, the DotNetNuke core installer calls the UpdateConfig method for each version (see Listing 2). This method checks that the file exists, creates an instance of the XmlMerge class and calls the UpdateConfig() method. Finally the StreamReader is closed to release the file systems lock on the file.
Listing 2: UpdateConfig method
|
1: Private Shared Function UpdateConfig(ByVal strVersion As String) As String
2: Dim strExceptions As String = ""
3:
4: Try
5: Dim strConfigFile As String = DotNetNuke.Common.HostMapPath & strVersion & ".config"
6:
7: If File.Exists(strConfigFile) Then
8: 'Create XmlMerge instance from config file source
9: Dim stream As StreamReader = File.OpenText(strConfigFile)
10: Dim merge As XmlMerge = New XmlMerge(stream, strVersion, "Core Upgrade")
11:
12: 'Process merge
13: merge.UpdateConfigs()
14:
15: 'Close stream
16: stream.Close()
17: End If
18:
19: Catch ex As Exception
20: strExceptions += "Error: " & ex.Message & vbCrLf
21: End Try
22:
23: Return strExceptions
24: End Function
|
In addition to using this in the core Installer/Upgrader - the new "Universal Extension Installer" that will be included in DotNetNuke 5.0 supports this ability too. Again - as an example lets look at a fragment of a manifest from the new installer (see Listing 3).
Listing 3: BroadcastPollingCachingProvider Manifest
|
1: <component type="Config">
2: <config>
3: <configFile>web.config</configFile>
4: <install>
5: <configuration>
6: <nodes>
7: <node path="/configuration/dotnetnuke/caching/providers" action="update" key="name"
8: collision="overwrite">
9: <add name="BroadcastPollingCachingProvider"
10: type="DotNetNuke.Services.Cache.BroadcastPollingCachingProvider.BPCachingProvider,
11: DotNetNuke.Caching.BroadcastPollingCachingProvider"
12: providerPath="~\Providers\CachingProviders\BroadcastPollingCachingProvider\" />
13: </node>
14: </nodes>
15: </configuration>
16: </install>
17: <uninstall>
18: <configuration>
19: <nodes>
20: <node path="/configuration/dotnetnuke/caching/providers/add[@name=
21: 'BroadcastPollingCachingProvider']"
22: action="remove" />
23: </nodes>
24: </configuration>
25: </uninstall>
26: </config>
27: </component>
|
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 - in this case web.config. 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 XmlMerge API is beyond the scope of this blog post, 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 source - the main entry points are the "UpdateConfig" methods.