This is my sixth revision DNN Upgrade guide.  This version of the guide includes important updates for working with DNN 4.8.0 and customized SqlDataProvider configurations.  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.  If a newer version of DNN has been released and I do not have a new version of this document, please use this version as there are most likely no breaking changes!

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.0 (or later) on a Remote Host" guide.

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.

Once you have completed your site backup you will want to download the DotNetNuke 4.8.0 install package from the DotNetNuke website.  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.  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. 

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.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.8.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: 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. 

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.

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!

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 1 <codeSubDirectories> section in your web.config, don't accidentally copy a second un-commented section as it will result in error.

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.

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.

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 I noticed that evey couple of installs would result in this direction 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.

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

Modify Search Localization Files

One optional item that is recommended after upgrading to 4.8.0 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.

Comments/Suggestions/Questions

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.