DotNetNuke is one of the easier platforms to upgrade but with a long version history the path to go from an old version to a new version isn’t clear.
It is important to not skip major versions when upgrading as the code to upgrade core components can’t handle the infinite possibilities.
The basic plan
Before starting an upgrade its best to make a good backup
- Backup the web.config file and change the extension to .txt for easy reading.
- Backup all of the web folder files into a zip file.
- Backup the database
- Add the database backup and the web.config text file backup of the web.config to the zip file.
- Upgrade your SQL Server version if needed
- Upgrade Plug-ins and Skins/Themes if needed
- Open your web.config and make sure autoupgrade is set to FALSE
- Unzip the new installation to a directory
- Copy the contents of the directory to your installation. I use a one-way file sync program.
- Open a browser and go to the upgrade URL
http(s)://<URL>/install/install.aspx?mode=upgrade - When it finishes test your site and sub-portals
Upgrade Path
All installation and upgrade files can be downloaded from GitHub for DNN 8 and later. Link to the old CodePlex archive for DNN v7 or earlier files. This file is 23GB as it contains all distributions.
If your current version falls between any of the versions listed below, first upgrade to the version closest to yours.
| From Version | To Version | Milestones, Requirements and Notes |
| 2.0.4 | 2.1.2 | Use the install package. Manually compare the web.config files |
| 2.1.2 | 3.1.1 | DNN v3 and later requires asp.net 1.1 Use the install package. Manually compare the web.config files |
| 3.1.1 | 3.2.2 | Use the install package. Manually compare the web.config files |
| 3.2.2 | 4.3.7 | You must have the v2.0 of the .NET framework installed or the upgrade will fail Use the install package. Manually compare the web.config files |
| 4.3.7 | 4.6.2 | Use the install package. Manually compare the web.config files |
| 4.6.2 | 4.9.5 | The post-4.6.2 upgrade procedure that runs is designed to remove unnecessary files, and would also make any web.config changes necessary for the upgrade. Use the Upgrade package and not the install package. See the process below. |
| 4.9.5 | 5.4.4 | Starting with v5.2 SQL needs to be SQL2005 or the upgrade will fail. Requires v3.5 SP1 Use the Upgrade package and not the install package. See the process below. |
| 5.4.4 | 5.6.8 | Use the Upgrade package and not the install package. See the process below. |
| 5.6.8 or any v6 | v6.2.8 | Use the Upgrade package and not the install package. See the process below. |
| 6.2.8 or any v7.x.x | v7.4.2 | Name changed to Evoq. Requires .NET: v4.0 IIS: 7.0, 7.5, 8.0, 8.5 SQL Server: 2008 Express to 2014 Use the Upgrade package and not the install package. See the process below. |
| v7.4.2 or any v8 | v8.0.4. | Requires .NET V4.51 IIS: 7.5, 8.0, 8.5, 10 SQL Server: 2008 R2 Express to 2016 Use the Upgrade package and not the install package. See the process below. |
| v8.0.4 any v9 | v9.2.2 | Prior to v9.2 there were over 500 API calls marked for deprecation that were removed from DNN in v9.2. Use the Upgrade package and not the install package. See the process below. |
When using the upgrade package
- Backup the web.config file. I like to use the web.config.v<insert full version number prior to the upgrade>.txt as the file name.
- Unzip the upgrade package into a new directory
- Copy the files over the existing installation directory. I use a file sync program set to one-way sync.
- Navigate to http(s)://<Your site URL>/install/ to begin the upgrade process.
- Test your sites
Important parts of the web.config
TIP: Use WinMerge
Using WinMerge or a similar program to help find the section that are different and copy them over to the new web.config.
Connection Strings
Copy Connection Strings settings found under <connectionstrings> and <appsettings> sections of your web config.
Machine Key and Validation Key values
One of the uses for the Machine Key and Validation Key values is to encrypt the password table and if they don’t match users will not be able to login.
<system.web>
<machineKey validationKey ="<value to copy>" decryptionKey="<value to copy>" decryption="3DES" validation="SHA1" />
Code Sub directories
These are used to control varies plug-in and custom code development. It’s important to check with the developer if these sections are current
Example:
<codeSubDirectories>
<add directoryName ="sub-directory name"/>
<codeSubDirectories >
Installation Date Application Setting
It’s not that important but if you want to change it the you need to find and modify the InstallationDate Application Setting.
<add key ="InstallationDate" value ="9/21/2006" />
Modify Search Localization Files
After upgrading to 4.5.5 you should modify the localization file for the search.ascx control to include your own Google Adsense id rather than the one for DotNetNuke.
If you do not have your own Google AdSense id you can get it from the Google AdSense website. You can modify this value by using the language editor and navigating under:
/Admin/Skins/App_LocalResources/Search.ascx.resx.
The value you need to change is directly after the “&client=” portion of the URL.
Common Errors
Upgrading to v5.4.0 failed to update the HTMLEditorProvider and Ribbon Bar Control
Enabling the Telerik RAD Editor requires you to make a change to the DotNetNuke web.config file. This file is found in the root of your website on the file system and must be access either from the server’s console or via FTP.
- Open the file up find the following section of the web.config file
<htmlEditor defaultProvider=”FckHtmlEditorProvider”> - Change the defaultProvider=”FckHtmlEditorProvider” setting to be defaultProvider=”TelerikEditorProvider”
- Save the file
- Perform an IISRESET
Enabling the Ribbon Bar Control Panel requires you to visit the Host/Host Settings page.
- Scroll down to the Other Settings section
- Expand that section of the page.
- In the dropdown list for the Control Panel Setting choose the RIBBONBAR setting.
- Update your Host Settings
- Test it
You receive the error: “Type ‘Web.HttpResponse’ is not defined”.
This error happens when the XML module is already installed but it did not upgrade.
- Find the “download.vb” file in the App_Code\XML\Handlers directory
- Edit line 34
FROM: Private Sub RenderToResponseStream(ByVal Response As Web.HttpResponse, ByVal controller As XmlController)
TO: Private Sub RenderToResponseStream(ByVal Response As System.Web.HttpResponse, ByVal controller As XmlController)
- Edit line 89
FROM: Private Sub handleAuthenticateRequest(ByVal context As Web.HttpContext)
To: Private Sub handleAuthenticateRequest(ByVal context As System.Web.HttpContext)
Side note:
In both edits you simply need to fully qualify the Web.HttpResponse as a System.Web.HttpRespone to comply with the latest .NET
References
- https://www.dnnsoftware.com/wiki/suggested-upgrade-path
- http://www.willstrohl.com/Blog/PostId/102/Suggested-DotNetNuke-Site-Upgrade-Paths
- Private communication with DNN support staff 😉
Did you get a clue?
If you got a clue and want to thank me, then visit the thank me page. It’s the best way to keep me publishing articles and keeping this site operation.
This site uses affiliate links. When you go to another site from here the link typically will have an affiliate code attached to it. Your actions on that site may earn a small commission for me. Read our affiliate link policy for more details.
{fin}