This is my eighth revision DNN Upgrade guide. This version includes an important
notice regarding the need to upgrade to take advantage of the most recent security
inprovements provided in DNN 4.8.3. Many portions of this upgrade guide are the same as previous versions, however, there are some new items and many minor changes/clarifications. This is simply due to the LIMITED changes that have truly occured in the area of DotNetNuke upgrades. This should be the final
version of these guides for the 4.x DNN platform, keep an eye our for 5.x guides
shortly before the public launch of DNN 5.x.
This guide is geared towards performing an upgrade in-place directly to the server. If you are on a hosted web server you will need to make modifications to the instructions to fit your access to the production environment. Additionally I STRONGLY suggest attempting to perform an upgrade locally BEFORE you update a production hosted site to check all processes, then use a method to deploy the upgrade in a prompt manner to minimize site downtime. If there is enough demand I will post a "Upgrading DotNetNuke from 4.x to 4.8.3
(or later) on a Remote Host" guide.
Need to Upgrade?
One of the most common questions that I get asked on a regular basis is "do I really need to upgrade"? Typically in the past I have answered this question with
slightly mixed reviews. At this time however my opinion has changed, in light
of recent activities in the community I STRONGLY recommend that if possible you
upgrade to the most current version of DNN as soon as you can adequately test and
deploy the upgrade.
This change in recommendation is due to the high publicity of recent security fixes
in the framework and the efforts of a group of individuals targeting DotNetNuke
sites for improper file uploads.
Even though the upgrade process is fairly simple and should not result in any critical errors it is very important that you perform a FULL site (file system) and database backup prior to starting your upgrade. Having a backup grants you a few options should a situation arise where your portal doesn't function correctly on the new version of DotNetNuke. Be sure to validate the integrity of your backups before continuing. If you would like information on how to backup a DNN installation you may view my "Backing up a DNN site and database" tutorial.
Once you have completed your site backup you will want to download the DotNetNuke 4.8.3 install package from the DotNetNuke website, this package may not quite be
available at the time of this article being posted, but it will be coming soon.. I will explain what you need to do with this momentarily. For those that have used my install guides in the past I have changed my opinion on the usage of the install/upgrade packages. I have found that it is safer to use the "install" package to do the upgrade. The main advantage to using the install package is that critical core DNN modules will be updated as part of the installation process. Typically this only includes the Text/HTML and a few other modules. The only downfall to using this package for upgrades is that it DOES include a web.config file, you must backup your existing web.config before applying the update, but I cover this process in detail below! If you have compelling reasons to not use the Install version you may use the upgrade version, however, there will be slight differences when using that package with this guide.
Once you have validated your backups and downloaded the most recent version of DNN you will want to backup your favicon.ico file if you have a non standard icon. I recommend temporarily re-nameing this file to something like favicon_site.ico so that it will not get overwritten in the upgrade process. A second alternative to this would be to stage the upgrade on another folder before overwriting and remove the favicon.ico file from the upgrade files.
If you DNN site relies on multiple third-party modules as most of them do, you will want to do a quick bit of research on the software vendor sites to ensure that no breaking changes were introduced with this newer DNN version, or to validate that you will not also have to upgrade the module as well. The full extent of this process is not something that I can directly explain in the course of this guide, this is why it is important to test first, then do the actual upgrade.
The last item that you should do prior to starting the upgrade process is to create an "app_offline.htm" file. This is a simple HTML document that you can place in your DNN root directory and it will take your website offline. This serves two purposes; first you prevent your users from experiencing any errors as the files are copying and secondly you prevent anyone else from accidentially triggering your upgrade process before all files are uploaded. For my websites I simply put a notice that the site is temporarily unavailable due to upgrades in process, this same message will be displayed to visitors from ALL portals. You MUST remove this file before you will actually be able to trigger the upgrade, that is why we will turn off "AutoUpgrade" later in this guide!
At this time you will want to test that the app_offline.htm file is working by simply trying to navigate to your site, you should see the content of your app_offline.htm file instead of your site content.
Update Web Configuration (Copy from old)
Now that your backups have been completed (including favicon.ico), you have the 4.8.3 package downloaded, and you have created your app_offline.htm file and tested to ensure it is displaying to users we are ready to actually perform the upgrade. First, you will want to rename your current web.config file to web.config.old. This will keep the file around as in a few moments we will be merging settings from this file into the new web config file.
Now you need to extract all files from the 4.8.3 install package into your root DNN folder. You will need to confirm the overwriting of your files. Once this process has completed, rename the release.config file to web.config and perform the following tasks using the information from your web.config.old file.
NOTE: a web.config file is included by default with the 4.8.3 install package, please
do not use that file, but use the release.config as named above.
NOTE: You will need to delete any existing web.config file before renaming release.config, be 100% sure that you have a backup of your original file before doing this!
NOTE: If you are on a shared hosting environment you are most likely completeting these changes on your local machine and can still have your production site active. This depends soley on how/where you are extracting files.
Update Connection Strings
Be sure that the proper connection strings are loaded for your setup, both in the <connectionstrings>and <appsettings> sections of your web config, examples are provided below. With these settings remember that you should only have 1 value per section and that it MUST not be commented out!
NOTE: in the example below I have simply REMOVED the second format of connection
strings, I find this format much easier to read, you may do the exact same yourself
< connectionStrings >
< add name ="SiteSqlServer" connectionString ="<yourconnectionhere>" providerName ="System.Data.SqlClient" />
< appSettings >
<!-- Database connection string (SQL Server 2000 or 2005 - kept for backwards compatability - legacy modules -->
< add key ="SiteSqlServer" value ="<yourconnectionhere>" />
Turn off AutoUpgrade
By default DotNetNuke will be set to "AutoUpgrade", this means that the first user to hit the default.aspx page on any portal within your DNN installation will trigger the upgrade process. This is typically not a desired result as if an error occurs you might not be able to see the error log since the other individual started the upgrade. The way around this is to update the "AutoUpgrade" appSetting, if you set this to "false" you will be required to navigate to the <yoururl>/Install/Install.aspx page to perform the upgrade.
< add key ="AutoUpgrade" value ="False" />
Copy Machine Key and Validation Key Values
Another very important item to copy over is your machine and validation keys. These are the keys used to encrypt and decrypt passwords and other information within your application. If you forget these items your users will not be able to login to the system. This declaration is typically just after the opening <system.web> tag. Below is an example of the machine key, the values you will be concerned with are the ones that note "<value to copy>".
TIP: If after the upgrade you are unable to login these values are the first ones that you should check!
< system.web >
< machineKey validationKey ="<value to copy>" decryptionKey ="<value to copy>" decryption ="3DES" validation ="SHA1" />
Copy CodeSubDirectories Section (if used)
Depending on the modules you have been using in your website you might have a <codeSubDirectories> section within your web config. If you have this section and it is NOT commented out you must be sure to copy this section otherwise you will encounter a compile-time error and your site will not display!. DotNetNuke will automatically add this section if you installed a module that uses C# as its programming language rather than VB. If this section exists it is a sub-element of the <compiliation> section of your config file. Below is a sample of what this section might look like.
NOTE: You might have multiple directory names listed
TIP: Be sure to only have one <codeSubDirectories> section in your web.config, don't accidentally copy a second un-commented section as it will result in error.
< codeSubDirectories >
< add directoryName ="sub-directory name"/>
< codeSubDirectories >
Copy the InstallationDate Application Setting (If Exists)
The last standard configuration element that needs to be copied over is the InstallationDate key. This is used to identify the time of last installation, it is a good idea to copy this over even though it does appear to be an optional step according to DNN documentation. Below is the format for the key, it is contained within the <appSettings> section.
NOTE: If you have installed dnn 4.5 and later only this setting most likely will NOT exist in your web.config and should not cause any difficulties.
< add key ="InstallationDate" value ="9/21/2006" />
Copy Object Qualifier and Database Owner Values (if used)
If when you completed your first DNN installation you specified special settings for Object Qualifier and/or database owner in the providers section be sure to copy these values to the new web.config file.
Copy any other custom configuration options or added config sections
If you have customized any other configuration settings or added new sections to the configuration you will want to add those to your new web config file at this time. One section you might want to quickly check is the httpRuntime section as many individuals have modified this section to allow for larger file uploads and you will want to be sure to copy those settings. Once you have completed this, it is time for the next and final step!
TIP: The usage of a file comparison tool might help you quickly identify any other "custom" sections of the web.config that you need to update. WinDiff is an application others have mentioned is helpful.
NOTE: If using a custom provider (HTML or FriendlyUrl) be sure to copy those settings
Start the Installation Process
After completing the above setup you are now ready to start the upgrade process. You will need to delete your app_offline.htm file if you created one so that you can access your site again. Now simply navigate to <yourSite>/Install/Install.aspx. If you are directed towards an "Under Construction" webpage please simply try this request again. In my testing with DNN 4.8.3 I noticed that evey couple of installs would result in this redirection on the first attempt at upgrading. In some cases I needed to try it 3-4 times to get the upgrade to start, just be sure that on your additional attemts that you are trying to go to install/install.aspx and not directly to the under construction page. After a few attempts it will ALWAYS
Once the page appears you should see a status screen that shows you the progress as the site is upgraded. At the end you should see an upgrade complete message with a link to your portal. You should not see ANY errors on this page, if you encountered an error be sure to note ALL information displayed so you can investigate the issues. This status screen should look like the following.(obviously displaying 4.8.3 for you)
Modify Search Localization Files
One optional item that is recommended after upgrading to 4.8.3 is to 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. This way you get credit for the adsense links!
Known Upgrade Issues
The only known breaking upgrade issue that I am aware of is for users that have the Active Directory Authentication Provider activated with auto login enabled. If you have this funtionality enabled in your existing site, please be cautious when upgrading your DotNetNuke site as it is possible that your site will be unavailable after upgrade. Per the Active Directory Provider forum on DotNetNuke.com the fix is to install version 01.00.02 of the provider BEFORE the upgrade.
One common question that I get from people is which version of DNN is safe to come from with a single upgrade to 4.8.3. In my experiences I have found that if you are on a version < 4.4.1 that it is best to first upgrade to 4.4.1, then to 4.6.2, then to the most current version. I know people that have had success with direct upgrades, but I have found them to be more successful following this pattern. If you are currently on a version between 4.4.1 and less than 4.6.0 I would recommend going to 4.6.2 first, then going to 4.8.2.
The main reason for this recommendation is due to the major changes in 4.4.1 regarding site performance and in the 4.6.x version and the authentication provider system.
Please share comments and suggestions below. If you have a question regarding a specific error message or an error that you have experienced please use my support forums to keep the comments here clutter free.