We recently attended a 2 day training event with Kentico in their Bedford, NH office to learn how Kentico recommends performing upgrades and learning how the other experts in the Kentico industry perform their upgrades.  On average we do about 12-13 Kentico upgrades per year.  These upgrades range anywhere from a single major version upgrade with little to no customizations to multiple major version upgrades with hundreds or thousands of lines of custom code.  So what we were hoping to get out of this training were a few nuggets which will help us be a bit more efficient.



Kentico has really evolved in the last 12 years and so has the upgrade process.  Like any web content management system (WCMS) there are typically breaking API changes from one major version to the next.  Kentico is no different.  


What we're going to provide you with today is an overview of what we do for upgrades and more specifically an upgrade from version 9 to version 10 of Kentico.  If  you're on an older version of Kentico you need to make sure you upgrade in sequence.  It's not simply upgrading from version 8.0 to 10.0 with a few clicks, you need to upgrade from 8.0 -> 8.1 -> 8.2 -> 9.0 -> 10.0 for the upgrade to work as expected.  

Upgrade Overview

 

Recently, we upgraded 2 instances of Kentico: our own kehrendev.com and another instance which we host and provide Kentico as a service which has multiple sites within it.  Both instances were running Kentico 9.0.36 or better and both instances have custom webparts, global handlers and other custom code in them.  Two of the biggest reasons we chose to upgrade both instances are:

 

• Simply testing the upgrade process for future projects and
• Performance!

 

If you haven't read, there are a couple good articles out regarding Kentico's performance in version 10.  Here's one from Michal Kadek, the "guardian of the core layers of Kentico".  Here's another from Brian McKeiver, a long time Kentico MVP, Co-Founder of BizStream and a great friend of ours.  

 

Upgrade Details

Here are the details for the article specifically pertaining to upgrading:
 

• both instances configured within Visual Studio as web sites running .NET framework 4.5.x
• both instances running Kentico 9.0.x (hotfix is not pertinent for this article)
• both instances running on a single server (Windows 12 VM) with no web farm enabled
• both instances running with SQL Server 2014
• both instances have similar custom code in /App_Code, /CMSFormControls, /CMSWebParts
• 1 instance is running multiple sites/domains with Kentico Ultimate licenses
• 1 instance is running Kentico EMS features

 

As you can see, nothing too crazy from a setup aspect.  The custom code includes some global event handlers, output filters, scheduled tasks, custom form controls and webparts.

 

Upgrade Preparation

 

Pro Tip: Before performing any of the upgrade process, make sure your maintenance agreement is current so you are able to get a version 10 license key.

When moving to Kentico 10, one of the things you'll want to make sure you take advantage of is the use of the Roslyn compiler.  This will reduce the first page load by almost 50% in comparison to other versions.  For those of you who work in the Kentico UI, you will see this change immediately and love every minute of it!

When you follow the actual upgrade path and use the Kentico Installation Manager (KIM), the Roslyn compiler will NOT automatically be added or installed in your project by performing the upgrade.  So you'll need to add it using the NuGet Package Manager and search for "Microsoft.CodeDom.Providers.DotNetCompilerPlatform".  In our case, we started with a fresh instance of Kentico 10.0.0 so this was not needed.

You might ask why we started with a fresh code instance of Kentico 10.  We do this simply because there are typically residual files that may or may not be removed during the upgrade process and this helps to ensure they are not around and causing problems later on.  If you have a highly customized version of Kentico, then maybe this is not the right path for you and maybe you want to follow the full upgrade path.  You'll have to evaluate that yourself when the time comes.  By no means are we exporting a site and importing a site using the Kentico UI, this method is NOT supported as an upgrade.

For the actual upgrade environment setup we had:

 

• our code base in our code repo copied to a local machine
• a fresh Kentico 10 instance on a local machine
• a copy of the current databases we were able to run scripts against  
• code base on local machine setup in IIS as a website connected to the copy of the current database to ensure everything is running and can perform the upgrade

 

Upgrade Code Process

 

Our first step in the upgrade process was to open the current code base in Visual Studio and make sure everything still compiled after a fresh get from the repo.  As with any developer and project there were no errors!  Next, we opened the fresh Kentico 10 instance, cleaned up all the unnecessary files, and made sure it too compiled without errors (which of course it did).

Then we started merging custom code files from the current website, a Kentico 9 instance, to the fresh install of a Kentico 10 instance.  We started with the easy files to get that immediate feeling of success:

 

• /App_Themes - design files
• /CMSScripts/Custom - javascript files 
• /<sitecodename> - media library files
• /CMSFiles - uploaded database files

 

Then we moved on to the C# code files in the /App_Code directory.  These in my opinion are the most crucial to get working right away because they can actually cause the site to crash if it won't properly compile.  Another reason these are important is your other custom form controls, webparts, etc, might be dependent on them.  So migrating them first is a must.  As we started updating files we read the release notes in detail and found a major change in the API for our modules:
 

The CMSModuleLoader partial class and the CMSLoaderAttribute class are now obsolete.

The process for moving modules and custom classes to the correct setup isn't difficult but you'll want to make sure you are no longer using the old definitions and migrate to the new setup, which was available in version 9 but since we just upgraded our v8 instances to v9 and didn't look at the warnings, we didn't make any major changes.

Another piece we noticed was with our webparts.  All our custom webparts needed to have a different "using" statement in them in order for the inheriting CMSAbstractWebPart class to be valid.  We added the namespace "CMS.PortalEngine.Web.UI" to all of our custom webparts.  

There are other API changes and changes you'll need to look out for.  One commonality we found was moving namespaces to <namespace.classname>.Web.UI.  For instance CMS.Controls is now CMS.DocumentEngine.Web.UI.  Again, this only applies to your custom code, all the other base code will be upgraded automatically.  Again, double check the release notes for detailed changes.

After all of the changes to the custom code we moved and the project actually built successfully, we moved on to the database upgrade process.
 

Database Upgrade Process

Next we performed the upgrade to the backup database by finding the upgrade.sql script found in C:\Program Files (x86)\Kentico\10.0\Upgrade90_100\SQL after you download and install from the DevNet.  Run this script against your backup database and ensure it succeeds.  Ours took about 2 minutes to run.  

After this step, connect your fresh Kentico 10 install with the migrated custom code base to the upgraded backup database and run the site.  Very important step not to miss: always run the site after an upgrade and a hotfix before trying to apply another upgrade or hotfix.  
 

Pro Tip:  Never navigate to the root of the domain or site, always navigate to the <domain>/admin section of the site.  This will ensure a very simple, quick startup of your site without needing to run any custom macros or code in your pages.

The first page you should be directed to is a page stating you don't have a license for this domain.  As stated earlier, make sure you're current on your Maintenance Agreement so you can get your upgrade license key in your client site, from your Kentico Partner or Kentico.  

After you enter your valid license key, review the Event Log.  This should be the first place you go after entering your license key to review.  Look for the event records stating Upgrade to 10.0 "Start" and "Finish".  If you don't see the "Finish" record in the event log, something failed.  You will have to restore your database back to v9 and start again.

As of right now, the code is upgraded and so is the backup database.  Navigate around a bit on the site and perform your normal tests in the front end and within the Kentico UI.  After you've successfully passed all your tests, you're ready to perform the upgrade on your production environment.
 

Upgrading Production

 

For us, upgrading production was fairly simple because the sites were able to handle a 5-10 minute downtime window.  So what we did was perform the upgrade on the backup environment to make sure everything tested out and the upgrade succeeded.  

We then did a fresh pull from our code repo to upgrade the code in production.  Be sure your repo includes .exe files otherwise the Roslyn compiler will NOT work!  As the repo was updating the production code, we performed a fresh backup of production for safety sake and ran the scripts to upgrade to v10.  

Pro Tip: If you're able to have some downtime on your site, stop the application pool your sites are running under.  This will help the backups and upgrade process move along a lot faster and ensure no others are able to connect before you are finished with the upgrade.

After the scripts were ran and code was updated, we started the application pool again and the site came up with an error.  Yes hard to believe but we had an error.  As I mentioned earlier, be sure your repo is including those .exe files otherwise it will crash because the Roslyn compiler files are missing.  After we added those files into the repo and synced them with production, things came up without issue.  

 

Conclusion

Although the upgrade process can be pretty in-depth, it really goes by pretty quick if you do it often enough.  Two things to remember:
 

• Always upgrade in iterations (8.0 -> 8.1 -> 8.2 -> 9.0, etc)
• Always run the site after each upgrade and hotfix are applied before trying to upgrade to the next version.  

If you need assistance, don't hesitate to contact someone who has been through the upgrade process and knows what they are doing.

Good luck and Happy Upgrading!