I recently went through an upgrade from a custom compiled DotNetNuke release 4.0.3.  It was interesting to say the least, but I faced quite a few challenges.  All of which would have been so much easier if I just thought about what I was doing instead of blindly following someone else's guide for the upgrade.

Keep in mind for minor revisions where you are only upgrading to a release that is a couple revisions newer the upgrade process SHOULD be fairly straight-forward.  In the past, when upgrade from 4.7.x, or 4.8.x to version 4.9.x it was as simple as unzipping the upgrade package and copying the contents into your website folder overwriting whatever files already exist.  Since this was a major jump in revisions, I assumed at least some things had changed significantly enough that I'd do a search on the Internet for a guide on the upgrade.  I couldn't find anything to go from 4.0.x to 4.9, but I did run across Mitchell Seller's guide to upgrade to 4.5.x. Following the steps in his guide, I tried to upgrade to 4.9.1, but kept getting some strange issues and errors along the way.  Sometimes the "upgrade" process would install a completely new instance of DotNetNuke.  Other times, the upgrade process would fail with an "Object Reference not set to an instance of an object" error, sometimes in the Membership Provider, sometimes in the GetHostSettings routines.

Here are the steps I've gone through to finally get the upgrade to successfully complete...Of course props to Mitchell and his guide, but one of his final steps glosses over the areas where I had issues, so I thought I'd write my own upgrade guide adding some of the specific steps on which I had issues

Backups

First and foremost, make sure you have a GOOD BACKUP of both the database and your website folder.  During this site upgrade, I restored both the site folders and the database probably 50+ times.  So I can't stress this enough.  Even if the upgrade does successfully complete, you might that the release of DotNetNuke that you are upgrading to has incompatibility issues with some of the modules that you have installed on your site.  Also, if you have any custom files in the site that DotNetNuke provides with their installation/upgrade packages (favicon.ico), you'll need the backup folder for a copy of those files to restore to the site folder.

Taking the Site Offline

If you have a site that has any significant traffic, then it will be important to let your users know what is happening during the upgrade process.  Since the release of 4.0.x, DotNetNuke has been targeted to version 2.0 of the .Net framework.  One of the neat features that came about in ASP.NET 2.0 (part of the .Net v2.0 framework) is the ability to place the "app_offline.htm" file in the root of the website folder.  If this file exists, ASP.NET will automatically display this to user's trying to access the site.  It provides a friendly and easy way to display a maintenance page to your users.  When the upgrade process is completed, all you have to do is remove the app_offline.htm file from the website's folder, and your site will be live again for users.

Keep in mind, you do not have to make any changes in IIS to have the site start showing the app_offline.htm file, it will automatically start displaying if it exists.  As noted in Scott Guthrie's article above (app_offline.htm link), you should also ensure the file size of the app_offline.htm is over 512 bytes, or Internet Explorer will display a "friendly error" instead of your maintenance page.

Updating your web.config

If you are not logged in locally to the server (like a shared hosting environment), you will likely need to do the following steps on your local PC, and only upload the modified web.config.

Because of changes that might have occurred (or in my case, DEFINITELY have occurred) in the web.config, it is recommended to rename your existing web.config to something like web.config.old, and then rename release.config to web.config.  Load both files up in your text/XML editor of choice as we'll be copying items from the web.config.old to the new web.config file.

Look for the <connectionStrings> section, and copy the active "SiteSqlServer" connection string from the old file to the new.  If you aren't 100% sure which one is active, you could copy over the entire <connectionStrings></connectionStrings> section from the old file to the new file.  You will also need to look for the legacy connection string in the <appSettings> section of the web.config file and ensure it is updated from your old file. 

It is recommended (especially if you opted not to use the app_offline.htm file), that you update the <appSettings> key "AutoUpgrade" to "false", to ensure that you start the upgrade process (and thus see any output from it), instead of one of your users.

The last Item in the <appSettings> section of the web.config to remember to copy over is the "InstallationDate" key.  I'm not 100% sure what this is used for, but I'd copy it over just to make sure, since DotNetNuke created the key.

In the <system.web> section of the web.config, you'll find a <machineKey> element that contains a ValidationKey and a DecryptionKey.  Copying over this line(s) from your old web.config is VERY important, as this is used for encrypting and decrypting passwords (and other information) in the database.  If you forget this step, when your upgrade is complete and you try to login to the site, you will get an invalid password response from DotNetNuke.  It can be corrected by updating these values in the web.config from the old web.config file.

Locate the <codeSubDirectories> element next, and if any modules have added a folder, you'll need to copy them over to the new web.config.  By default the web.config has the <codeSubDirectories> section commented out, so you'll need to copy the start and end tags for the <codeSubDirectories> section, or uncomment them.

When I was doing my upgrade, I ran a file comparison utility and noticed the default MembershipProvider had changed some time between 4.0.x and 4.9.x (and 5.0.x).  Initially I was copying over from my old config the entire <membership> section of the old config, as I was (incorrectly) assuming that the change in MembershipProvider would keep me from logging into the site after the upgrade.  While the change didn't seem to affect the final outcome of the upgrade, it appears that the DotNetNuke team successfully migrated from one default provider to the other without breaking anything.  So I'd recommend leaving these settings AS IS in the new web.config.

Finally you should check the remainder of the config file for custom settings, especially the <dotNetNuke> config sections that contain provider information and settings for those providers.  The main mistake I was making during my upgrade process, and what resulted in a new instance of DotNetNuke being installed (instead of an upgrade of the existing instance), was not looking at the <data> provider section under <dotNetNuke>.  In my case, the line was too long to be viewed on my screen, and since I never scrolled over to look at all the settings, I didn't notice that an "objectQualifier" had been specified for the SQLDataProvider.  It is key that both the "objectQualifier" and the "databaseOwner" attributes match up between your new web.config and your old one.

Removing old DLLs

I'm not exactly sure when the changes in the DLLs being distributed with DotNetNuke occurred, but at some point around 4.5.x several of the core DLLs were consolidated, and other DLL changes occurred as well.  The challenge with this is that ASP.NET wants to analyze (Reflect) over each of the DLLs and the older DLLs even though not being used anymore will cause ambiguous references, or other issues.  In my website's bin folder I had 20-30 DLLs that matched DotNetNuke.*.dll.  Unfortunately some of those are core modules developed by the DotNetNuke team, but not affected by the DotNetNuke framework upgrade.  So, I ended up deleting all DotNetNuke.*.dll files that were not DotNetNuke.Module.*.dll, and then re-copying in from the upgrade package all DLLs from the bin folder.

Doing the ACTUAL upgrade

At this point you are ready to open a web browser and go to (your URL)/Install/Install.aspx?mode=upgrade.

If all goes well you should see "Upgrading DotNetNuke", followed by the "Current Assembly Version", "Current Database Version", and several other items.  If the process completes successfully at the bottom of the page you should see "Upgrade Complete" followed by a link that says "Click Here to Access Your Portal".  Follow the link, and browse the site both as an anonymous user, and as a logged in user and admin.  Ensure that everything is working as expected.  You'll need to remove the app_offline.htm file to bring the site back online.

BACKUPS BACKUPS BACKUPS

I figured it was worth mentioning again that you are STRONGLY ENCOURAGED to do both a website folder backup as well as a database back before attempting any of these steps.  It'll be well worth the trouble if anything goes wrong than trying to have to re-build the site from scratch because of a failed upgrade.

Known Errors and possible solutions

Server Error in '/' Application.

--------------------------------------------------------------------------------
Runtime Error
Description: An application error occurred on the server. The current custom error settings for this application prevent the details of the application error from being viewed remotely (for security reasons). It could, however, be viewed by browsers running on the local server machine.

• First and foremost change the <customErrors> element to "mode=off" in your web.config, restore your original website folder and database, and start over.  Hopefully you'll get better information about what actually went wrong.  Just remember to change the <customErrors> element back to "mode=RemoteOnly" afterwards.  No sense in making your site users see the Yellow Screen of Death.
• Check for errors in your copying of elements from one web.config file to another.  Small errors like missing a closing tag could cause the whole file to appear invalid to ASP.Net.

Object reference not set to an instance of an Object

• I saw several variations on this error, but all ultimately ended up being a result of incorrectly copied, or lack of being copied settings from the old web.config.  Double check to ensure you don't have some custom setting information somewhere that hasn't been copied over to the new config.

SqlDataProvider Error! (see x.x.x.log for more information)

• The best advice I can give on errors like this are check the site's functionality, and if all appears to be working OK, then you probably shouldn't worry about it.  It's difficult at best for the DotNetNuke team to make sure that all of their SQL scripts are 100% compatible with all previous versions of the DotNetNuke schema.

I hope this guide helps.  I wouldn't wish the hair-pulling frustration that I experienced during my upgrade from 4.0.3 on anyone.  If I can be of any help, please don't hesitate to contact me, or post a comment below.