Multi-version Upgrades: Alternate Approach

The process:

If you’re part of an agency that doesn’t frequently perform upgrades, or part of an organization that is upgrading its own site internally, this approach should work for you.

1. Set up a copy of the site in a sandbox environment, where you plan to perform the upgrade.
2. Follow the steps to prepare the site for the upgrade as described in documentation. You can make the upgrade process a lot smoother by getting the site in a predictable state by removing recycle bin objects and object version history, moving virtual objects into the database, etc.
3. Once the instance is prepared for the upgrade, add an app_offline.htm file to the CMS folder of the project (or the root in Kentico 7 and older). This leaves the files in tact but does not allow them to process requests or interact with the database.
4. Install a new instance of Kentico of the same version and hotfix as your project. Installation with database is not necessary; you will only need the file system.
5. Point this new application to your existing database by updating the connection string.
6. Upgrade your site to the next version normally, according to the upgrade instructions. Then, make a request to the /Admin login page of the site, and check the event log for the START and FINISH events.
   1. The reason that I specifically recommend the /Admin login page of the site so that missing components, such as custom web part files and scripts, don’t cause errors.
   2. I also recommend taking a backup of the file system and DB at each step in case there are errors in the following upgrade step.
   3. Do not continue upgrading if you receive errors during the SQL script portion of the upgrade.
   4. If you are missing one or both of the upgrade events, or there are errors in between them, do not continue upgrading.
7. Repeat the previous step for each version, until you reach the target version.
8. Copy physical files (images, CSS, etc.) from the old file system into the newly upgraded one.
9. Merge customizations from the original project into the new file system, updating API usage where necessary.

Extra resources for Frequent Upgraders:

If you’re an agency who takes on many upgrade jobs, and plans on performing multi-version upgrades on a regular basis, this extra preparation may help in the long run. Instead of hooking the database up to a new application and bringing them up together every single time, you can prepare upgrade applications ahead of time, so you can skip the step that overwrites the filesystem at every version.

1. Install a fresh instance of Kentico of the oldest version you plan on regularly upgrading from.
2. Upgrade the site to the next version.
3. Create a backup of the filesystem, and store it somewhere that it can be accessed and copied for future reuse.
4. Repeat this process for every Kentico version until you reach the most up-to-date.

Members of your agency who regularly perform upgrades can take copies of the backups, configure them as applications in IIS, and use them to bring a customer’s database up through the in such a way that only the SQL script is required, and the copying/overwriting files portion can be skipped. The general process will be something like this:

1. Start with a copy of the customer’s database, which has been prepped for the upgrade according to the documentation (Empty recycle bin and object version history, virtual objects in database, etc.)
2. Run the upgrade SQL script on the database.
   1. by default, the sql script can be found in <drive>\Program Files (x86)\Kentico\<version>\Upgrade<previousversion>_<version>\SQL\upgrade.sql.
   2. There is a separate set of scripts to use if you have a separated OM database, which can be found in the Separation folder.
3. In the application that is one version ahead of the database, change the connection string to point to the database.
4. Make a request to that application.
   1. I recommend using the default login page, like ~/Admin (or ~/CMSSiteManager for older versions) to make this requests so that nothing being referenced on the actual site’s pages can cause issues.
   2. This will trigger the upgrade procedure, which updates important data within the database.
      1. Make sure you check for the event log for the START and FINISH events, and any errors that might have occurred.
5. Remove or alter the connection string so it is no longer pointing to the database, and repeat from step 2 for the next version.

There are a few notes I’d like to share about this process.

• Please take backups from an upgraded filesystem for this, rather than creating a clean install of the target version. The installers for some versions of Kentico do not have the right versions of UpgradeProcedure.cs, so they will not work properly.
• When you move on from one version to the next, be sure to clear the connection string of the version you are done with, so that it can no longer make calls to the database.
• As long as you don’t copy any custom code into these applications, they can be re-used for the next upgrade. Once you get a site to its target version with this approach, make sure to copy the file system and merge the customer’s custom code into the copy, so the one you will use for upgrading other sites remains clean.