When a new version of a CMS arrives, it likely brings many benefits (like new features, bug fixes, and performance improvements). But what does it take to upgrade to the latest and greatest? This article will outline the upgrade process for Kentico, an ASP.NET CMS platform.

Before You Begin

Upgrading to a new version of Kentico involves changes to the site’s database, Kentico’s core code, and custom code added to the site by you or other developers. With so much changing, you’ll want a code and content freeze before getting a local copy of the site to begin the upgrade.

Note: Each Kentico upgrade from version to version is a separate upgrade, and you must perform each upgrade in sequence. For example, upgrading from Kentico 7 to Kentico 11, you need to do separate upgrades for each major version: K7 > K8 > K8.1 > K8.2 > K9 > K10 > K11.

Things You Will Need

  • A local copy of the site’s files
  • A local copy of the site’s database
  • Kentico license(s):
    • For your local environment, each version of Kentico from the current version to the target version
    • For the live domain, the target version of Kentico

Initial Prep

Before starting any Kentico upgrade, the site should build in Visual Studio with no errors. Depending on the state of the site, this may be a non-issue or a considerable amount of work.
Additionally, it would be helpful to remove any code or data which is not being used. Large database tables which are no longer used or have more data than is necessary to keep (inactive contacts which are never removed is a prime example) can greatly speed up the database upgrade process. And removing unused custom functionality before the upgrade means less custom code for you to update.

Before starting on the actual upgrade, use the Kentico Code Upgrade Tool to help you fix what will soon become deprecated code.

Kentico’s Code Upgrade Tool

Kentico provides code upgrade tools to automatically update code where it can, and make recommendations everywhere else. You would use this tool before performing the upgrade to the next versionCurrently, there are versions for moving between Kentico versions 7 through 11.

Download the correct version of the code upgrade tool for your version of Kentico, and follow the instructions provided. A typical process would include:
Putting the site into “deployment mode” (temporarily putting virtual objects like transformations & page layouts into the file system so the tool can check them for issues).
Running the code upgrade tool from the command line using the “Automatic Conversion” option.

When run this way, the tool will create a .csv file pointing out code that will cause issues in the next version of Kentico. It will specify filenames and line numbers, the code in question, and recommended fixes.

It will also create updated copies of files it was able to fix automatically in a separate directory. After performing the Kentico upgrade, changes in these files can be merged into the upgraded site.

After running the code upgrade tool, take the site back out of deployment mode (putting virtual objects back into the database) before beginning the Kentico upgrade.

Performing the Kentico Upgrade

The upgrade itself can be downloaded from the Kentico Installation manager. Make sure to make a backup of all the site files and the database first, and follow the directions provided.

The database change scripts may take a long time to run, and in some cases could time out. Larger databases and slow network connections would have an effect on this. You may need to go into the installer files and run the update scripts manually within SQL.

Kentico will keep custom files, and preserve customized Kentico files by adding the new versions with a “.new” extension. After the upgrade, you will need to port any custom functionality in the older, customized versions of these files to the new versions.

After the Upgrade

You can now update any custom code that needs it. This includes customized code files in the project, as well as virtual objects (like transformations and page layouts).

Enable deployment mode, which should move all virtual objects to the filesystem. If you ran the Code Upgrade tool, you may have some upgraded files you can copy into your project, as well as a spreadsheet of recommended changes. Go through the list of recommended changes in Visual Studio and make any necessary changes to get the site to build.

For remaining errors, you can currently find a searchable list of API changes between versions of Kentico from V7 through V10 at https://devnet.kentico.com/documentation/api-changes. If Visual Studio is showing an error for a class or method, look for it in the API changes. A library may have been moved, or method arguments may have changed.

Once the site builds with no errors:

  • Clear your cache and visit the upgraded site
  • Take the site back out of deployment mode
  • Re-sign all macros
  • Add new Kentico licenses for the site(s)

Now that the upgrade is complete, you can test to make sure everything is working as expected.

Conclusion

Upgrading to a new version of Kentico can bring some great benefits, and you should now have a better idea of what is involved. If you’re looking for assistance with your Kentico upgrade, Wakefly can help. We’re a Kentico Gold Partner as well as a Kentico Quality Expert.