With this post I would like to share my ideas when it comes to upgrading Kentico to the latest version. I believe that upgrading Kentico is a good practice, not only to leverage new features as a developer, marketer or content admin, but also to make sure the software keeps up with the current technology like .NET frameworks, browser support and is up-to-date from a security perspective. This post is not specific to any Kentico version.
Upgrade prerequisites
Before we begin upgrading there are a couple of things to consider for every Kentico upgrade:
- Clean the Event Log to get a good overview what happens during the upgrade process
- Disable Emails and prevent unwanted mailings from being sent out
- Disable Continuous Integration
- Disable Content Staging and clear all tables
- Disable Web Farms and clear all tables
- Consider cleaning the on-line marketing data to prevent timeout issues
- Check for running Worker Threads and make sure nothing unexpected is running on the background
- Enable deployment mode for virtual objects to store important database objects in the file system (for compilation purposes explained later in this post)
- Create backups of your Kentico files and database if you want to start over in case the upgrade fails
- Check the release notes and read specifically through the system requirement and breaking changes
Don’t forget to reenable certain modules after the upgrade has completed!
Understanding the upgrade procedure
I have done plenty of upgrades ever since I started working with Kentico around version 2. I have witnessed the introduction of the Kentico Installation Manager (KIM) and tools to help you do the upgrade as smooth as possible. What helped me the most is
understand how the upgrade works.
In the most simplest form the upgrade does two things: 1) it changes Kentico files and 2) it makes changes to the database. While this seems easy, there is actually more than meets the eye. Let me breakdown this process and zoom in on both areas.
Upgrading the Kentico files
The Kentico files are referred to as the actual Kentico solution with its project files. In the early days I was a big fan of website projects. This was mainly because you could change files on the (production) server and you could view the result without building the solution. As our projects got bigger and bigger this model did not feel right anymore. We
switched to the web application project type and instantly improved code quality by introducing build servers that automatically compile and test the code after each check-in. For everyone still on the website model I recommend you to
convert your project type from website to web application before you start your upgrade.
If you have used the Portal Engine as development model then some objects like page templates, transformations and web part layouts are stored in the Kentico database. Compilation takes place in memory on the webserver. In order to ensure that these objects still work after upgrade, it is important to include them in the upgrade process. The best way to handle this is to store them as virtual objects in the file system. You can then compile them together with the rest of the solution.
For the actual upgrade of the Kentico files I use the
Kentico Upgrade Utility which you can download from Kentico DevNet. The utility allows you to switch to advanced mode and handpick the actions that you want to upgrade:
I would deselect the “SQL script” and “Rebuild web project” options to be in complete control over this step. After performing the upgrade of the Kentico files the most likely outcome is that either the step was successful (yay) or you get a warning that one or more modified files have been found and that you will have to manual resolve them/merge your changes. Let’s take a closer look at that last warning and consider some alternatives.
Whenever you are planning to make changes to Kentico source files it is good to understand the risks and act upon them. In the case of upgrades you will need to address changes in the Kentico files to prevent a lot of unexpected work. Fortunately the Kentico Upgrade Utility detects customized files and adds the original file with the .new extension so you can easily locate them, compare with and merge your changes into. Personally I would like to prevent this from happening as much as I can. That is why I would recommend: 1) if possible
do not change the Kentico files and 2)
put custom code in separate projects. If you stick to these rules then upgrading Kentico will be so much easier.
On the subject of custom code I want to keep it short and simple and refer to the
Kentico code upgrade tool that is available on Kentico DevNet. The Kentico code upgrade tool provides a way to analyze your Kentico project and help convert custom code to the new Kentico version. This is also a good moment to
consider upgrading the .NET framework version.
Once you have upgraded the Kentico files, virtual objects, custom code and potential .NET framework version it’s time to rebuild the solution. The possible outcome is either build succeeded (again yay) or one or more build errors in which case you need to fix with or without help of the Kentico code upgrade tool. In case of build errors I always tend to compare the project files with a fresh Kentico installation. Please make sure you are comparing the same hotfix versions. Finally compare the upgraded web.config with a fresh installed web.config and make sure there’s nothing strange inside.
Upgrading the database
The second part of the upgrade process exists out of getting our database upgraded to the new version. Like I stated earlier the key here is to be in control of the whole upgrade process. That is why I prefer to do a manual upgrade of the database versus the next, next, finish approach that the Kentico Upgrade Utility offers. In one of the earlier upgrade steps we installed the
Kentico Upgrade Utility. Remember the “SQL script” option that we deselected? We are now going to manually execute the contents of this SQL script on our Kentico database.
Fire up Microsoft SQL Server Management Studio, logon your database server and open a new query window on your Kentico database. Locate the “upgrade.sql” SQL script inside the version specific upgrade folder e.g. “C:\Program Files (x86)\Kentico\11.0\Upgrade100_110\SQL\” and execute it on the Kentico database. In case your project uses a separated on-line marketing database then execute the SQL scripts from the Separation folder first “separated.sql” then “default.sql”. Usually when I run into errors at this point they are typically data inconsistencies that I can easily fix myself. Simply restore the database, fix the inconsistencies and reapply the upgrade SQL script. Alternatively it would be best to send the error log to Kentico support.
Before we continue with the next important upgrade step I would recommend you to
increase the Connection String timeout value. On more than one occasion I have had timeouts breaking my Kentico upgrade. Especially when upgrading on lower Azure database pricing tiers. You can simply avoid this by increasing the timeout value during upgrades and change it back once you’re done.
The next step is triggered when you start the web application and originates from a couple of files that were added during the upgrade of the Kentico files. If you take a closer look at the “Old_App_Code\CMS” folder you will notice a file called “UpgradeProcedure.cs” and a corresponding file called “Upgrade_100_110.zip” inside the “CMSSiteUtils\Import” folder. This is a Kentico module that runs once if the version of the Kentico database is older than the version of the upgraded code. Among disabling Kentico CI, importing objects and refreshing Macro signatures, It’s kind of a mystery what happens inside this code. What I do know is that it will definitely change the database. I would recommend not touching either the web application or database during this initial request of the website, to ensure that there is enough time to execute all of the needed changes. The best way to verify that this part of the upgrade completed is to query the event log for a log containing e.g. “Upgrade to 11.0” and “FINISH”. Overall the event log should not contain any errors during the upgrade “START” and “FINISH” events.
If all went well Kentico should load in your browser indicating that you would need a valid license. I would recommend
clearing your browser cache to ensure that the new CSS and JavaScript files load correctly and you should be good to go.
Final thoughts
I hope this post helped you to get a better understanding on how Kentico upgrades work. The intent is not to replace the Kentico documentation. Instead I still heavily encourage you to read the Kentico upgrade documentation as it is constantly being finetuned.