Upgrading to DotNetNuke 4.6.0 from 4.x
This is my fourth revision DNN Upgrade guide. This version of the document includes important updates for the upgrade process to DotNetNuke 4.6. Many portions of this upgrade guide are the same as previous versions, however, there are some new items. This is simply due to the LIMITED changes that have truly occured in the area of DotNetNuke upgrades.
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.
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 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. 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.6.0 install package from the DotNetNuke website. I will xplain 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 just overall much safer to use the "install" package to do the upgrade, and you get the upgraded core modules at the same time, using this I have found my upgrade times to be a small amount faster, you may still use the "upgrade" version if you desire working from a 4.x upgrade.
Once you have the backups in place if you have a favicon.ico file saved for your website that is different than the standard DotNetNuke one you will want to temporarily re-name 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. 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.
Configuring Your Setup
Now that your backups have been completed and you have the 4.6.0 package downloaded 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.6.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 origional 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.
<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>".
<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. 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. Below is a sample of what this section might look like. NOTE: you might have multiple directory names listed
<codeSubDirectories>
<add directoryName="sub-directory name"/>
<codeSubDirectories>
Copy the InstallationDate Application Setting
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. 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 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!
Start the Installation Process
After completing the above setup you are now ready to start the upgrade process. You will want 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.6 I noticed that evey couple of installs would result in this direction on the first attempt at upgrading.
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.
Modify Search Localization Files
One new item that is recommended after upgrading to 4.6.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!
Please feel free to share any comments/concerns below! If you have specific questions, please use my DotNetNuke forum to ask those questions!
Posted by Mitchel on Monday, September 17, 2007
Click here to post a comment