What Happens During a Kentico Upgrade?

1. The Filesystem

The first thing the upgrade utility does is overwrite parts of the filesystem. Both assemblies and system code files are overwritten. In some cases, files and folders may also be created, moved or deleted as well. A good example is the 7.0 to 8.0 upgrade, in which the CMS folder was created, becoming the root of the project. Although system files are overwritten, virtual files are not upgraded during this process. If you are using Deployment mode, make sure to store virtual files in the database prior to upgrading. This will allow them to be updated at a later point in the upgrade.

When overwriting files, the upgrade utility uses a checksum to tell whether or not the files have been modified. If it detects that a file has been changed, it will not overwrite the file, but instead will leave it intact and create a “.new” file. If this happens, it’s up to you to manually merge any customizations you made to the old file into the “.new” file, get rid of the old file, and rename the new file to remove the “.new” extension. The application will be left offline so you have a chance to make these fixes

If you’re going through the manual upgrade, this part will be up to you. After taking your site offline, you will remove all of the system files listed in “upgrade.xml” from your project directory, copy the new upgrade files into your project, and then merge in any of your customizations from your backups.

Either way, it can create a lot of extra work during an upgrade if many of the system files have been modified. We recommend that you avoid modifying the system files whenever possible. If you must customize them, try to keep a detailed log of the customizations and clearly mark your code with comments or regions. This way, you’ll know which parts are custom when merging.  

Note that in Kentico 11 and newer, the upgrade will also install certain required NuGet packages, and therefore will require internet access.

2. The SQL script

The next key part of the upgrade is the SQL script. The upgrade utility runs this script after overwriting the filesystem, but manual upgraders must execute the script using SQL Server Management Studio. The SQL script makes changes to the schema and data in the database. During its execution, tables, views, indexes, procedures, columns, constraints, and functions can all be added, removed, or modified.

Some data can also be inserted, deleted, or updated by this script, including settings keys, UI elements, and user controls. During this part of the upgrade, the “CMSDBVersion” settings key is updated to the target version of the upgrade process.

Your database might be especially susceptible to errors during this process if you have made direct customizations to it. Adding custom columns, indexes, constraints, or views can also lead to issues. In some cases, customizations can cause the script to fail, and in other cases, they can be overwritten by the upgrade. Databases from instances that were not completely upgraded to their current version, or which have imported objects from older versions also experience errors frequently. You can check the “CMSDBVersion” and “CMSDataVersion” settings keys to see if an instance appears to have been fully upgraded to its current version, using a query like SELECT KeyName, KeyValue FROM CMS_SettingsKey WHERE KeyName IN ('CMSDBVersion','CMSDataVersion')

If you experience an error during the SQL script, make sure that you roll back before addressing the causes of the error. Re-applying the script over a partially upgraded database will not work and is not supported. It can be helpful to keep track of the changes you had to make in order to get the SQL script to complete successfully, especially in case you have to upgrade multiple environments.

3. The Upgrade Procedure

When the first request is made to the site after the filesystem is overwritten and the SQL script has finished, a special class called “UpgradeProcedure.cs” runs. This upgrade script can make changes to both the filesystem and database, and it is of vital importance to the upgrade. You might even consider this procedure the true upgrade, with the previous parts just making the necessary preparations. Make sure you access the site so this script can run before applying any hotfixes on your instance.

This procedure imports and overwrites many default Kentico objects, such as web parts, transformations, and page types. It deletes and re-creates the system views, migrates data where necessary, clears cache and hashtables, re-signs macros, removes routes from the system, and inserts metafiles. It also updates class form definitions to reflect changes made to the code files and database tables. It is during the execution of this script that the “CMSDataVersion” key is updated to the target version.

The Upgrade START event is logged at the beginning of the execution, and the FINISH event is logged at the end. These events are vital indicators of whether the upgrade ran all the way to completion. The presence or absence of errors in between them can also indicate whether or not the execution succeeded. After you are able to log into Kentico, make sure you check the Event Log to see if the script was successful. This must be done at each step of the upgrade if you are upgrading across multiple versions. If you can’t log into Kentico, or want to check the progress of the script as it is still running, you can check directly in the CMS_EventLog table with a query like SELECT TOP 10 * FROM CMS_EventLog ORDER BY EventTime DESC.

If “UpgradeProcedure.cs” is unable to run to completion or experiences errors, you should first roll back, then re-apply after making any changes to address the errors. If it runs into any errors during execution, it should write to the Event Log. The event should reveal where the execution failed, which could shed some light on the steps necessary to fix it. One example could be if the upgrade times out during execution. Online Marketing related tables, like OM_Contact and OM_Activity, can bloat if not managed properly, causing these kinds of issues. Culling some data from these tables prior to upgrading should solve the issue. Bloating can also happen in object and page version history, and in the Recycle Bin, depending on how they are configured. These, however, should be cleared prior to upgrading, as described in our documentation.

If the upgrade procedure does not complete, but does not log any errors in the event log, it is usually a result of the application restarting mid execution. This could happen if you have virtual memory limits or CPU limits on the application pool that your site is on. There is also a bug in Windows Server 2012 R2 that caused the application pool to restart when many writes were made to the App_Data folder. You can read about this issue and how to fix it here.