Upgrading to DotNetNuke 4.5.1 from 4.x
Due to popular request this article is an updated version of my DNN upgrade
process. Below I will walk you through all steps necessary to upgrade
your DNN website from a previous 4.x version to the most current version
4.5.1. This article is based on my first upgrade document as well as
incorporating new recommendations such as the use of an app_offline.htm file
and other items of that nature to provide a better user experience, especially
for those of us using shared hosting providers where the file copy process can
take a while. Users upgrading to other 4.x versions should be able to use
this guide successfully, however, I know this works 100% for upgrades to 4.5.1
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 I have a blog posting regarding backup procedures here on this
site.
Once you have completed your site backup you will want to download the
DotNetNuke 4.5.1 UPGRADE package from the DotNetNuke website. I will
explain what you need to do with this momentarily.
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.5.1 upgrade package
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.5.1 upgrade 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
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.
<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.
<add key
="InstallationDate" value
="9/21/2006" />
Copy any other custom configuration options
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?mode=upgrade. 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.
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 Friday, May 04, 2007
Click here to post a comment