Upgrading DNN 3.x to DNN 4.x
Recently I have noticed an increased number of questions regarding the upgrade process from DNN 3.x to DNN 4.x and overall I do not think there is very much good documentation available on how to actually complete the upgrade. Therefore with this article I will walk you through the process of upgrading a 3.x site to 4.x, I will try to cover as many of the "gotchas" as possible, but please remember as with all of my other tutorials PLEASE use these at your own risk!
Prerequisites
Prior to completing the upgrade following these instructions you should make sure that each of the following statements are true!
Your DNN Version is 3.3.5 or 3.3.7
I have had much greater success upgrading to the 4.x platform when using either 3.3.5 or 3.3.7 as the base version of DotNetNuke for the upgrade. If you are on a previous version of 3.x or 2.x I would recommend an incremental upgrade to take you to 3.3.5 or 3.3.7 before continuing with the upgrade per these instructions.
Your Webserver Supports .NET 2.0
Another important factor to note when performing this upgrade is that your hosting server must support .NET 2.0, typically this is not an issue but you should be aware of what is needed to switch the .NET runtime version for your website. If you are on shared hosting the methods vary and you might need to contact technical support to have the version changed, this all depends on the features of your provider's control panel. The instructions in this guide will cover this change using IIS directly; users on shared hosting must substitute their provider's instructions for those steps.
You have taken a complete site backup!
I cannot stress the importance of this item enough! Be sure prior to attempting an upgrade that you have a full site and database backup, you will need these backups in case something goes wrong during the upgrade. For instructions on how to create a backup please see my tutorial on "Creating DNN Backups".
You have validated that all installed modules will work with 4.x
An often overlooked portion of the upgrade process from 3.x to 4.x is making sure that all of your modules will work successfully with the new version of DNN. This is something that isn't necessarily 100% as there are many unknowns, however I do recommend researching the modules via the developers website to obtain information regarding its use with the 4.x platform.
You have downloaded the 4.x Install Package
The last prerequisite to performing the site upgrade is to ensure that you have downloaded the "Install" version of DNN 4.x that you wish to upgrade your site to. At this time the most current version is 4.5.3 however these instructions should work for any 4.x version. You must NOT use the upgrade package as it does not necessarily contain all needed files.
Starting the Upgrade
The upgrade process can take a significant amount of time to complete so the first thing that I like to do is to switch my application over to the 2.0 framework and then provide an app_offline.htm file to provide a message to the users. I typicaly perform this step as the first part of a 3.x -> 4.x upgrade as this way I can take the site entirely offline and still provide my users a detailed upgrade message. The use of app_offline.htm is ONLY supported by ASP.NET 2.0 therefore we must perform this switch early on.
The first step is to create the app_offline.htm file. This is a static HTML document that will be served to our users while we perform the various file manipulations necessary to upgrade the site from 3.x to 4.x. You may place any content desired in this file then save it as "app_offline.htm" to the ROOT of your DNN installation. Once we update the .NET Framework version to 2.0 it will serve this page as the only content for the site until we delete the file!
Change Virtual Directory to .NET 2.0
Below are the instructions to change your DNN virtual directory to ASP.NET 2.0 using the IIS tool within Windows XP. If you are on a different version of Windows (Vista, 2003) these instructions might be slightly different. If you are on a shared hosting provider please use their instructions and jump to the "Testing The app_offline.htm File" section of this tutorial.
- Open the Control Panel
- Click on "Administrative Tools"
- Click on "Internet Information Services"
- Expand the websites node and right click on your virtual directory
- Switch to the "ASP.NET" tab and change the version to "2.0.50727", then press Ok
- You may now exit from all other open windows, including IIS and the control panel
Testing the "app_offline.htm" File
Now that you have performed the above IIS change to ensure that everything is configured properly for the rest of the upgrade you should try to navigate to your website. When you pull up your website the ONLY content you should see is the "app_offline.htm" file. If you see this content please continue on, if you do not please retrace the above steps and ensure that the file is in the proper location with the proper name and that ASP.NET 2.0 is selected.
Rename Existing Web.config
The final thing to do in preparing to upgrade is to rename your existing web.config file. I do this to ensure that the file is not accidentally overwritten. I recommend renaming the file to "web_3x.config" this way that you can easily find it.
Unzip the 4.x Install Package
The next step of the process is to unzip the 4.x install package, you should unzip this and extract all files OVER the existing files for your website. You want to make sure that ALL files are replaces as it is VERY important that no existing 3.x files exist.
File Removal (4.5 and later only)
After unzipping the installation package if you are going to DNN 4.5.0 or later you will need to manually remove a few .dll files from your website's bin directory. These dll's were previously used by the Text/HTML module which was integrated into the DNN core after version 4.5.0. If you find either of the following files in your bin directory you must delete them.
- DotNetNuke.Modules.Html.dll
- DotNetNuke.Modules.Html.SqlDataProvider.dll
Update/Merge release.config
The final step in the upgrade process is to update/merge the release.config file with the information from your existing web.config file, each sub-section below will discuss 1 action that you will need to take to validate/merge the information.
Rename release.config
To prepare for the final site upgrade you must rename the release.config file to web.config. This file is the standard production configuration of a DotNetNuke website for the upgrade version. We will now merge your existing settings into the file as well as change a few existing configuration items to set your site up for long term success!
Copy Connection Strings
Your existing web.config file (which you should have renamed to web_3x.config) has 1 connection string and it should look like the following:
<add key="SiteSqlServer" value="Server=YourServer;Database=YourDb;uid=YourUser;pwd=YourPassword" />
The new web.config file contains 2 different locations for connection strings, you will need to copy the values from the "Key=" Section of your existing to your new web.config file. After copying the values you should have the following in your new web.config file. (This would be towards the top of the file)
<!-- More options exist above this section..... -->
<connectionStrings>
<!-- Connection String for SQL Server 2005 Express -->
<add name="SiteSqlServer" connectionString="Server=YourServer;Database=YourDatabase;uid=YourUser;pwd=YourPassword;" providerName="System.Data.SqlClient" />
</connectionStrings>
<appSettings>
<!-- Connection String for SQL Server 2005 Express - kept for backwards compatability - legacy modules -->
<add key="SiteSqlServer" value="Server=YourServer;Database=YourDatabase;uid=YourUser;pwd=YourPassword;" />
<!-- More settings exist below this line! -->
Note in my above example that I have removed the other declaration that ws provided as part of the default file but was commented out, this is done to make the web.config more readable.
Modify AppSettings To Prevent Auto Install
Another item that I like to do is to modify the application settings values to ensure that automatic upgrades are not completed. I also put an "installationDate" setting in the new file to make sure that DotNetNuke does not change our machine keys. Please see the below snippet and ensure that your configuration settings match the values below, if you do not have an installation date setting please add it. You will have other items in the AppSettings section but these are the only ones you need to change.
<add key="AutoUpgrade" value="false" />
<add key="UseInstallWizard" value="false" />
<add key="InstallationDate" value="05/01/2006" />
Copy Machine Key Values
In your existing application you will have two additional appSettings for MachineValidationKey and MachineDecryptionKey it is very important that you copy these values as not copying them will render all of your user accounts useless as the system will not be able to retreive the password. Below is what that settings should look like in your old web.config file, your values WILL be different.
<add key="MachineValidationKey" value="449FEF64C3792134D949DDAA20D29B5D4AB1C61A" />
<add key="MachineDecryptionKey" value="9C8288BA9F0C4F48B3D8FAF264F4BAA9C600CB31CA383354" />
These values will need to be copied to a slightly different location in your new web config file, to the "MachineKeys" tag. This section should look like the following in your new web.config, replace the existing values with those from your old web.config.
<machineKey validationKey="449FEF64C3792134D949DDAA20D29B5D4AB1C61A" decryptionKey="9C8288BA9F0C4F48B3D8FAF264F4BAA9C600CB31CA383354" decryption="3DES" validation="SHA1" />
Copy Additional Config Settings (If Needed)
The above should be all of the items that you MUST copy over to your new web config file, however, you should take an additional look over your old file to identify any other items that will need to be copied to the new file. Items to look for include appSettings, HttpModules, and HttpRuntime settings. It is impossible to list all of the possibilities of items that must be copied over, so if you have any questions as to what should/shouldn't be copied over please feel free to post a question in the forum on this site.
Running the Update
After completing all of the above steps you should now be ready to actually trigger the DNN upgrade process. To do this you need to first delete the "app_offline.htm" file that you placed on your site in the beginning. Then navigate to <YourUrl>/Install/Install.aspx where <YourUrl> is your websites URL. This should then trigger the upgrade process, you should see a series of progress updates then a completion message. Take note of any errors listed on this page, then click on the link to navigate to your portal. You should now have a fully upgraded DNN site.
Troubleshooting
If you encounter any difficulties when trying to run the upgrade to your site be sure to research/view any error logs that are referenced by the DNN installation process. Also if you have any third party modules be sure to check for known issues with the 4.x platform, also, it might be worthwhile to change to a default DNN skin to see if you potentially have an issue related to a 3.x skin.
If you are still unable to get your site working after reviewing the logs, modules, and skins you can revert to your backup or post your question either here or on DotNetNuke.com and someone can try to help you resolve the issues.
Conclusion
I hope this article has been a help to get your website upgraded to the latest and greatest DotNetNuke. If you encounter any difficulties during your upgrade please feel free to use my forums for questions. If you have any comments or suggestions regarding this article please leave it below!
Posted by Mitchel on Thursday, June 28, 2007
Click here to post a comment