September 04, 2008

Upgrading to DNN 4.9.0 from 4.x

This is my ninth revision DNN Upgrade guide.  Many portions of this upgrade guide are the same as previous versions, however, there are some new items and many minor changes/clarifications.  In addition notes have been provided for users on shared/remote hosting environments to help guide the way to a proper upgrade. 

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.  Helpful notes will be provided along the way to note changes that you might consider to get your remote upgrade completed successfully. 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 you have specific questions regarding remote host upgrades, and methods to upgrade with minimal site downtime please feel free to make a post on my forum and I'll gladly provide as much information as possible.

Need to Upgrade?

The most common question that I see when discussing DotNetNuke releases is "Should I Upgrade?".  The correct answer to this question really depends on a site by site basis depending on a number of factors.  However, 4.9.0 being the final release of the 4.x series is an upgrade that I will recommend people perform, it includes the last bits and pieces of fixes, enhancements, and security fixes that will exist prior to the release of 5.x.

Consideration on upgrades must always be taken to ensure that all installed third-party modules will successfully operate under the new version.

Getting Ready

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.  If you are on a remote hosting provider, you might need to contact your provider to obtain proper backups.

Once you have completed your site backup you will want to download the DotNetNuke 4.9.0 install package from the DotNetNuke website.  (NOTE: 4.9.0 is not yet available, but will be soon!)..  I will explain what you need to do with this momentarily.  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.9.0 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.9.0 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.9.0 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 if desired.

< connectionStrings >

< add  name ="SiteSqlServer"  connectionString ="<yourconnectionhere>"  providerName ="System.Data.SqlClient"   />
connectionStrings >
< 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 as well!

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.9.0 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 work.

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.9.0 for you)

Upgrade progress screen

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 the fix is to install version 01.00.02 of the provider BEFORE the upgrade.

Incremental Upgrades?

One common question that I get from people is which version of DNN is safe to come from with a single upgrade to 4.9.0. 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.9.0. 

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.

NOTE: If upgrading from a lower vesion, you may use the streamlined process to perform the final step of the upgrade from 4.6.2 -> 4.9.0.  Please see the respective article here on this site.


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.

tags: DNN, Tutorials, Announcements, DNN Administration, DNN Install/Upgrade
comments powered by Disqus

Content provided in this blog is provided "AS-IS" and the information should be used at your own discretion.  The thoughts and opinions expressed are the personal thoughts of Mitchel Sellers and do not reflect the opinions of his employer.

Content Copyright

Content in this blog is copyright protected.  Re-publishing on other websites is allowed as long as proper credit and backlink to the article is provided.  Any other re-publishing or distribution of this content is prohibited without written permission from Mitchel Sellers.