Upgrading to Kentico 12

This page provides instructions for upgrading Kentico projects from version 11 to 12.

1. Check the prerequisites and Upgrade overview
2. Install the upgrade procedure
3. Perform the required steps before the upgrade
4. Apply the upgrade to your Kentico project
5. Perform the required steps after the upgrade

Warning

Using the Export and Import features to move sites from older versions of Kentico is NOT a valid way to perform the upgrade. During such imports, you risk overwriting database objects and files with older equivalents that may not be compatible. The import may prevent your site and the system as a whole from working correctly.

Importing of packages from older versions is supported to allow transferring of single objects or basic data, not as a way to upgrade entire sites.

Prerequisites

Before you start the upgrade, please make sure that your environment fulfills the requirements of Kentico 12. See System requirements for details.

The upgrade must be performed on a machine with a working Internet connection.

Note: The upgrade must be applied to complete projects that use the standard folder structure (the CMS and Lib sub folders) and names of key files (the solution file, csproj project file, web.config, packages.config, GlobalAssemblyInfo.cs). You cannot directly upgrade web site deployments of the CMS folder – first upgrade the original complete project and then create a new deployment.

Upgrading across multiple versions

If you are upgrading from a Kentico version lower than 11, you need to go through a separate upgrade procedure for each version. Check the instructions for each upgrade version, and perform the required steps before and after the upgrade.

For each version, you always need to open the upgraded website in a browser before starting the upgrade for the next version and verify that the site loads correctly. When processing the first request after the upgrade, the system performs certain tasks required to finish the upgrade, including the import of new objects.

The same requirement applies even if you are only updating to a newer patch version by applying a hotfix to the upgraded project.

Upgrade overview

The following is a summary of the most important changes that the upgrade performs. To learn how to replace any removed features or components that you use, see the linked documentation or the required steps before and after the upgrade on this page.

• If your Kentico project’s Target framework version is NET Framework 4.6, the upgrade sets the version to 4.6.1 (the minimum .NET version supported by Kentico 12). Projects with a higher Target framework version are supported by the upgrade (the version remains unchanged).
• The upgrade integrates third-party libraries by installing the following additional NuGet packages into the Kentico project (and their dependencies):

  • DocumentFormat.OpenXml 2.7.2

  • linqtotwitter 4.0.0

  • MaxMind.GeoIP2 3.0.0

  • OpenPop.NET 2.0.4.369

  • System.IO.Packaging 4.0.0

    If your Kentico project already contains a different version of one of these NuGet packages, the upgrade either updates the package to the required version (for older versions) or does not change the version (for newer versions).

    In both cases, a binding redirect is automatically added to the project’s web.config file for the related assembly (either from your old version to the required version, or from the required version to your newer version).

• Custom files in the original project are transferred to the upgraded project.
• Customized Kentico files are preserved (does not apply if you choose to overwrite all files when applying the upgrade):
  • For each customized file, the upgrade creates the new Kentico 12 version (with the .new extension). You need to manually transfer your customizations to the new files and then replace the original ones.
  • Customized files that no longer exist in Kentico 12 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project in web application projects.
• If your Kentico project uses Windows authentication (integrated security) for its database connection, the database upgrade scripts automatically set the Default schema of the database user matching the current Windows account (i.e. the user who runs the upgrade utility) to the schema used by the objects in your Kentico database (dbo by default).
• The upgrade disables web farm and continuous integration functionality. You can re-enable the features after you complete the upgrade.

Class fields

• The upgrade overwrites the form definitions of the default fields of system classes and their alternative forms. Custom fields from the previous version are transferred over.

Default objects

• The upgrade procedure imports new versions of the following default objects (overwrites existing objects):
  • Web parts
  • Web part layouts
  • Widgets
  • Reports
  • Time zones
• The default Form control objects are overwritten (both the source files and form control objects in the system).

Content management

• Obsolete MVC functionality related to the CMSApp_MVC project was completely removed from the system. Page templates of the MVC type are changed to the Portal page type. MVC URL paths of pages are replaced by empty strings and all page aliases with the MVC Path type are removed.

Social & Community

• The Friends and Messaging features were removed from the system, along with all related components (web parts, widgets, email templates, form controls). See the Removed web parts section for more detailed information.

Installing the upgrade procedure

1. Download the Kentico 12 upgrade.
2. Run Upgrade_11_0_12_0.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\12.0\Upgrade110_120 folder by default).

Steps before you start the upgrade

Custom code analysis

If you have an MVC site or if your Kentico project contains any custom code (including virtual objects such as transformations), we strongly recommend using the Kentico code upgrade tool before you start the upgrade procedure.

Download the tool from the API Changes page on the DevNet portal. See Upgrading custom code to learn more.

The tool has the following functionality:

• Detects code that is no longer valid in version 12
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Kentico 12 API

The tool’s output will help you update the code of your projects after you perform the upgrade.

Required .NET Compiler Platform

Kentico 12 requires the .NET Compiler Platform (“Roslyn”) compiler to run, provided by the Microsoft.CodeDom.Providers.DotNetCompilerPlatform NuGet package. The upgrade automatically updates the package to version 2.0.1 (if necessary).

The updated version no longer requires the Microsoft.Net.Compilers package as a dependency, and we recommend uninstalling this package (unless required by your custom functionality).

Deployment mode and Source control

If your system stores virtual objects on the file system (due to enabled deployment mode or source control options), you need to return the files to the database before performing the upgrade.

You can re-enable deployment mode or source control after you finish the upgrade.

Staging, integration and export tasks

If your project uses staging or the integration bus, you need to synchronize all staging and integration tasks before starting the upgrade procedure. Synchronization of existing tasks from older Kentico versions may fail after you perform the upgrade. To perform the synchronization, use the Staging or Integration bus applications.

If you have the Settings -> Versioning & Synchronization -> Staging -> Log export tasks setting enabled, the system logs delete tasks when objects are deleted. These tasks can then be included in export packages and used to delete objects on other instances during the import. The data of logged delete tasks is NOT updated during upgrades, so existing tasks may not work correctly after you upgrade to a newer version.

We recommend clearing all delete tasks before you start the upgrade – go to Sites -> View export history -> Tasks and click Delete all tasks.

Object version history and recycled objects

The upgrade does NOT update the data of:

• Deleted objects in the Recycle bin
• Previous versions of objects

After you perform the upgrade, it may not be possible to correctly restore or roll back certain types of objects from the recycle bin or version history. Before you start the upgrade, we recommend reviewing the content of your recycle bin and version history:

1. Recover any data that you wish to use after the upgrade.
2. Permanently delete the remaining data.

Macro security

To successfully complete the upgrade, you will need to re-sign all macros after applying the upgrade. The upgrade procedure also re-signs the macros within certain object types automatically.

This can potentially be a security vulnerability, so we strongly recommend checking your system for invalid macros before you start the upgrade:

1. In the System application, select the Macros -> Report tab.
2. Enable Report problems and click Search.

If you detect any macros that have invalid signatures or are otherwise suspicious, fix or delete them. For more information, see Working with macro signatures.

Large database tables and timeouts

If some of your database tables contain very large amounts of data, timeout problems can occur when applying the database upgrade or during the processing of the first request after the upgrade. This may prevent the upgrade procedure from finishing successfully.

To avoid timeout-related issues, you can either increase the timeout settings of your SQL server for the duration of the upgrade, or try to clear unnecessary data.

For example, contact management features can generate a very large volume of contact and activity data on high‑traffic websites (in the OM_Contact and OM_Activity tables). You can trim down the data by running automatic deletion of contacts that meet certain conditions and are no longer relevant.

Full-text search for Kentico database tables

If you are using full-text search catalogs for any Kentico database tables, you need to remove the catalogs before starting the upgrade. The procedure drops and recreates indexes for most tables. You can set up the full-text search again after the upgrade is complete.

Removed web parts

The upgrade removes the following web parts:

• Friends list
• Friends viewer
• Friends waiting for approval
• Friendship management
• My friends
• My pending requests
• Rejected friends
• Request friendship
• Contact list
• Ignore list
• Inbox
• Messaging info panel
• My messages
• Outbox
• Send message

You need to replace or remove instances of these web parts on your site’s page templates. Use the following process:

1. Open the Web parts application.
2. Select the given web part and view the Usage tab.
3. Remove or replace any occurrences of the web part on your site.
4. If a web part is used by a widget or inherited web part, perform these steps for the given components (use the Widgets application for widgets).

After you remove or replace all occurrences of a web part, we strongly recommend that you delete it in the Web parts application.

Removed goo.gl URL shortener integration

The upgrade removes the goo.gl URL shortener for social media posts from the system. The Google URL Shortener service is discontinued and its API will stop working after March 30, 2019.

Before starting the upgrade, make sure that the goo.gl URL shortener is not used:

• In the Settings application, check the Social marketing -> Default URL shortener settings. If necessary, switch to a different URL shortener or select the (do not shorten links) option.
• In the Workflows application, check any advanced workflows that contain Publish to Facebook, Publish to Twitter or Publish to LinkedIn steps. If necessary, edit the steps and switch their URL shortener property to a different shortener or select the (do not shorten links) option.

If you do not remove usage of the goo.gl URL shortener from your system, you may encounter errors when posting to social media after the upgrade.

Applying the upgrade

We strongly recommend using the Kentico Upgrade Utility to perform the upgrade automatically.

Note: Before you run the upgrade utility, close any instances of Visual Studio where the target Kentico solution is opened.

1. Open the folder where you installed the upgrade.

2. Run the Kentico Upgrade Utility (Upgrade.exe).

3. Enter the path to your Kentico 11 web project folder (you can select a folder using the Browse button).

4. Use the utility to back up your project files and/or database if you have not done so already.

5. Select whether you want to upgrade files, the database or both. To successfully perform the upgrade, you need to update both the project files and the database. Only change the settings in special scenarios (for example when performing part of the process manually).

   Important: If you use a separated on-line marketing database, you need to disable the SQL script part of the upgrade:

   1. Click Switch to advanced mode.
   2. Clear the SQL script checkbox.Run the SQL scripts manually after the upgrade utility updates the project files (see Upgrading separated on-line marketing databases below).
   Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Kentico 12 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.

6. On web application projects, the upgrade utility rebuilds the solution at the end of the upgrade by default. If your project contains custom code that is no longer supported in Kentico 12, or has certain modules uninstalled, the rebuild will not be successful. You can disable the Rebuild web project option on customized projects, and perform the rebuild manually once you update the project after the upgrade.

7. Choose a method of taking the project offline and bringing it back online.

8. Click Next to start the upgrade procedure.

9. After the upgrade finishes, click Next to view any conflicts of customized files that occurred during the upgrade process. By default, the upgrade utility does not overwrite modified files in order to preserve your customizations (unless you enabled the Overwrite all files option in the upgrade utility):

   • For each customized file, the upgrade creates the new Kentico 12 version (with the .new extension). You need to manually transfer your customizations to the new files and then replace the original ones.
   • Customized files that no longer exist in Kentico 12 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project in web application projects.

10. The upgrade attempts to automatically update your project’s web.config file (unless you enabled the Overwrite all files option in the upgrade utility). The process may fail if your web.config contains certain types of customizations. In this case, a new web.config file is created in the web project’s CMS folder with the .new extension. You need to:

    1. Edit the new web.config and transfer over any customizations and the connection string from the original web.config.
    2. Move your original web.config to a different location.
    3. Rename web.config.new to web.config.

Close the upgrade utility.

Upgrading MVC projects

For websites created using the MVC development model, you need to upgrade your Kentico administration application (see above), and additionally update the Kentico code used by your MVC application:

1. Open your MVC application in Visual Studio.
2. Update your MVC project’s Target framework version to NET Framework 4.6.1 or newer (if necessary).
3. Right-click your MVC project in the Solution Explorer and select Manage NuGet Packages.
4. Uninstall all Kentico 11 integration packages for MVC development – Kentico.Web.Mvc, Kentico.Content.Web.Mvc, Kentico.Ecommerce, etc.
5. Install the Kentico.AspNet.Mvc NuGet package (use version 12.0.0 until you apply a hotfix to your upgraded Kentico project).

The new Kentico.AspNet.Mvc package combines the functionality of the original Kentico 11 packages. In many cases, the API of the packages was replaced by API provided as part of the Kentico.Libraries package, which is automatically installed as a dependency.

We strongly recommend that you additionally:

• Read about breaking changes related to the packages in the release notes.
• Run the code upgrade tool for your MVC project and use the provided information to update your code.

Upgrading separated on-line marketing databases

If your project uses a separated on-line marketing database, you need to manually run the upgrade SQL scripts after updating the project files:

1. Open the upgrade installation directory (C:\Program Files\Kentico\12.0\Upgrade110_120 by default).

2. Expand the SQL\Separation folder.

3. Manually run the script files in the following order:

   1. separated.sql (against the separated on-line marketing database)
   2. default.sql (against your main Kentico database)

Once the databases are successfully upgraded, continue with the steps after the upgrade.

Steps after performing the upgrade

After you apply the upgrade to your project, please check the following sections and perform the required actions. Go through the sections in the listed order.

API changes

You need to update your code according to the new API of Kentico 12, including:

• Code files in MVC projects that use the Kentico API
• Custom or customized code files in the Kentico web project
• Virtual objects in Kentico, such as transformations and page layouts (used by Portal Engine sites)

Use the output of the Kentico code upgrade tool to find occurrences of invalid code and recommendations on how to fix or replace them.

Tip: For Portal Engine sites, enable Deployment mode and fix the code of virtual objects in the corresponding physical files. This makes it easier to update the code of virtual objects according to the output of the code upgrade tool. Disable deployment mode to return the updated virtual objects back into the database.

You can also search for specific API resolutions on the DevNet portal

NuGet package consolidation

The upgrade updates the version of some of the NuGet packages installed within the Kentico web project. If your project already contains a different version of one of these NuGet packages, the upgrade either updates the package to the required version (for older versions) or does not change the version (for newer versions). In both cases, a binding redirect is automatically added to the project’s web.config file for the related assembly (either from your old version to the required version, or from the required version to your newer version).

If you have any custom projects within the solution that use the same packages or any of their dependencies, you need to consolidate the package versions:

1. Right-click the solution in the Solution Explorer and select Manage NuGet Packages for Solution.
2. Select the Consolidate tab, and make sure your custom projects use the same package versions as the Kentico web project (CMSApp or CMS).

If your Kentico project uses a higher Target framework than .NET Framework 4.6.1, we strongly recommend that you consolidate the target framework version for all installed NuGet packages:

1. Open your Kentico project in Visual Studio.

2. Open the Package Manager Console (under Tools > NuGet Package Manager).

3. Run the following commands:

   Copy

   
   
   
    Uninstall-Package -Id Rx-Main -Force -RemoveDependencies;
    Uninstall-Package -Id linqtotwitter -Force;
    Update-Package -reinstall;
    Install-Package -Id linqtotwitter -Version 4.0.0
   
   
    

The Update-Package command reinstalls all NuGet packages with the appropriate target framework version for your project. The other Uninstall-Package and Install-Package commands manually remove and add packages that could cause errors during the reinstallation.

404 handling on MVC sites

The Kentico 12 NuGet packages for MVC sites no longer provide the NotFoundHandler feature for handling of errors with the 404 status code. Instead, we recommend that you set up handling of 404 errors via IIS.

Web farm synchronization tasks

Kentico 12 introduces a new way of registering and creating web farm synchronization tasks. If you are using any custom web farm synchronization tasks in your environment, you need to refactor your custom code to comply with the new standard. See Creating custom web farm synchronization tasks for more information and a sample implementation of the new approach. 

Obsolete Attachment API

The Attachment class from the CMS.DocumentEngine namespace of the Kentico API is now obsolete and should be replaced with the DocumentAttachment class in any custom code.

If you have any page types with File or Attachment fields and use generated API classes to work with them, re-generate the given Info and InfoProvider classes. Alternatively, you can replace occurrences of the Attachment class in the code of these page types manually.

Assembly references

Kentico 12 brings the following assembly changes:

• CMS.CKEditor.Web.UI.dll merged into CMS.Base.Web.UI.dll
• CMS.Localization.dll merged into CMS.Globalization.dll
• CMS.ModuleLicenses.dll merged into CMS.Modules.dll
• CMS.ModuleLicenses.Web.UI.dll renamed to CMS.Modules.Web.UI.dll

You need to remove any manually added references from custom projects to the old assemblies. If necessary, add new references to the assemblies into which the code was merged. The changes do not impact the related API and namespaces.

Automated tests

The Kentico 12 version of the Kentico.Libraries.Tests NuGet package (CMS.Tests library) no longer supports the Microsoft unit test framework. If you have any tests built with this framework, you need to rewrite them to either use the NUnit testing framework or to work without the CMS.Tests library.

For more information, see the Writing automated tests chapter.

Kentico 12 setup files

The upgrade converts your web projects to version 12, but does not provide the associated setup files (i.e. the Kentico program files that are separate from individual web projects). The setup files contain external utilities, sample files, and allow you to install new Kentico 12 web projects.

To obtain the installer and setup files for Kentico 12:

1. Download the Kentico 12 installer.
2. Run Kentico_12_0.exe.
3. Read and accept the License Terms and Conditions and click Custom installation.
4. Select Install only program files and click Install.

Clearing session state data

Objects that are stored in the server-side session state may have a different structure in the upgraded version. The changes may cause errors for users who access the upgraded site with outdated session data.

If your application uses a session state mode that preserves data through application restarts (StateServer, SQLServer or Custom), you need to manually clear any existing session data after you perform the upgrade:

• StateServer – restart the session state service.
• SQLServer – delete the content of the session state database.
• Custom – depends on the implementation of the custom storage provider.

Running the website - First request

Important: This step must be performed before you apply any hotfixes to the upgraded project.

Open the upgraded website in a browser. For MVC sites, you need to open the URL of the Kentico administration interface (not the live site presented by the MVC application).

When handling the first request (i.e. on application start), the system performs certain tasks required to finalize the upgrade. Processing of the first request may take longer than usual. The first request also includes the automatic import of new web part, widget, report and time zone objects.

Once the website loads, sign in to the administration interface and open the Event log application. Check for the presence of any errors or exceptions between the Upgrade - Start and Upgrade - Finish events:

• If you find errors related to the object import, open the Sites application, click Import site or objects and try to import the upgrade_110_120.zip package manually.
• If any other errors are present or if the log does not contain the Upgrade - Finish event at all, the upgrade may not be fully applied. Please contact Kentico support and provide the details of the errors.

Licenses

You need to add Kentico version 12 licenses for the domains used by your sites:

1. In the Kentico administration interface, open the Licenses application.
2. Delete the old version 11 licenses.
3. Click New license to add your licenses for version 12.

Macros

To ensure that macros and the administration interface work correctly after the upgrade:

1. Sign in to the Kentico administration interface as a global administrator.
2. Open the System application.
3. Select the Macros -> Signatures tab.
4. Enable the Sign all macros option.
5. Click Update macro signatures.

The system resigns all macros. The new security signatures of all macros contain the username of your administrator account.

Validate that all macros in the system work correctly:

1. In the System application, select the Macros -> Report tab.
2. Enable Report problems and click Search.

For more information, see the Macro expressions chapter.

Web farms

The upgrade procedure automatically disables web farm functionality. If your Kentico instance runs on a web farm or you use the MVC development model, you need to enable web farms after you complete the upgrade.

We recommend that you enable the web farm on one server or instance and after that you add the remaining servers to the web farm.

1. In the Kentico administration interface, open the Settings application.
2. Expand the Versioning & Synchronization -> Web farm category.
3. Select the Web farm mode:
   • Automatic – if you wish to let the system handle the configuration of web farms servers.
   • Manual – if you need to control the web farm manually. See Configuring web farm servers.
4. Click Save.

MVC sites – Presentation URL

In Kentico 12, the Presentation URL of MVC sites must include the URL scheme (protocol). If you have an MVC (content-only) site, make sure that it fulfills this requirement:

1. In the Kentico administration interface, open the Sites application.
2. Edit your MVC site.
3. If necessary, add the URL scheme into the Presentation URL value. For example: https://www.mysite.com
4. Click Save.

Geolocation

The geolocation feature was updated to work with Maxmind’s GeoIP2 Databases.

If you use geolocation, you need to add the newer GeoLite2 or GeoIP2 database files into your web project. See Using geolocation for contacts for detailed instructions.

UI personalization

If you have UI personalization enabled for your site, we recommend reviewing the settings for all available roles. You may wish to enable access to new UI elements added by the upgrade (applications, tabs, etc.).

Upgrading source code instances

Kentico does not provide an upgrade package for source code instances. We recommend using the following process if you need to upgrade a source code project:

1. Obtain the new version of the source code solution.
2. Install the upgrade procedure.
3. Perform any relevant steps before the upgrade.
4. Merge all customizations from your old source code solution into the new one.
   • This mainly includes updates of custom API, verification of its relevance in the new version, and testing.
5. Apply the database upgrade.
6. Open the upgrade installation directory (C:\Program Files\Kentico\12.0\Upgrade110_120 by default), and copy the CMS\CMS\CMSSiteUtils\Import\Upgrade_110_120.zip file into the CMS\CMSSiteUtils\Import folder of the new Kentico 12 project.
7. Perform all relevant steps after the upgrade.