Is this really the version you are looking for? Kentico Xperience 12 Service Pack Documentation is no longer updated. Use the switcher in the header to choose your product version.
Kentico 12 Service Pack
If you already have Kentico 12 and wish to apply Kentico 12 Service Pack, you do NOT need to follow the upgrade process described on this page.
You only need to apply hotfix version 12.0.29 or newer to your project. See the Hotfix instructions to learn how to install the service pack via the hotfix.
This page provides instructions for upgrading Kentico projects from version 11 to 12.
Upgrading non-standard projects
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.
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.
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 (opens in a new tab) to the upgraded project.
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.
This does not include all Kentico 12 features and changes – see Release notes - Kentico 12 for a comprehensive list.
OpenPop.NET (opens in a new tab) 2.0.4.369
System.IO.Packaging (opens in a new tab) 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).
See the Release notes for highlights of the breaking changes in the Kentico 12 API.
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 (opens in a new tab) page on the DevNet portal. See Upgrading custom code to learn more.
The tool has the following functionality:
The tool’s output will help you update the code of your projects after you perform the upgrade.
Kentico 12 requires the .NET Compiler Platform ('Roslyn') (opens in a new tab) compiler to run, provided by the Microsoft.CodeDom.Providers.DotNetCompilerPlatform (opens in a new tab) 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).
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.
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 (opens in a new tab) -> 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.
The upgrade does NOT update the data of:
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:
Page version history and workflow
The instructions above only apply to the version history of non-page objects.
If your website's content uses workflow (or page versioning without workflow), you do NOT need to clear the version history of pages before starting the upgrade. Existing page versions and pages under workflow should work correctly after performing the upgrade.
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:
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.
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.
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.
The upgrade removes the following web parts:
You need to replace or remove instances of these web parts on your site's page templates. Use the following process:
After you remove or replace all occurrences of a web part, we strongly recommend that you delete it in the Web parts application.
The upgrade procedure deletes all source files of the listed web parts, but leaves their database records. If you do not manually delete them, these non-functional web parts and their categories may remain in your database after the upgrade, with a (Removed) suffix added to the display name.
The upgrade removes the goo.gl URL shortener for social media posts from the system. The Google URL Shortener service is discontinued (opens in a new tab) 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:
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.
We strongly recommend using the Kentico Upgrade Utility to perform the upgrade automatically.
Manual upgrade
If you cannot run the automatic upgrade utility, you can perform the upgrade manually. See Upgrading Kentico manually.
Note: Before you run the upgrade utility, close any instances of Visual Studio where the target Kentico solution is opened.
Open the folder where you installed the upgrade.
Run the Kentico Upgrade Utility (Upgrade.exe).
Enter the path to your Kentico 11 web project folder (you can select a folder using the Browse button).
Use the utility to back up your project files and/or database if you have not done so already.
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:
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.
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.
Choose a method of taking the project offline and bringing it back online.
Close the upgrade utility.
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:
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:
If your project uses a separated on-line marketing database, you need to manually run the upgrade SQL scripts after updating the project files:
Open the upgrade installation directory (C:\Program Files\Kentico\12.0\Upgrade110_120 by default).
Expand the SQL\Separation folder.
Manually run the script files in the following order:
Note: Kentico uses database objects with the dbo schema by default. If your database uses a different or no schema, you need to modify any schema occurrences in the script accordingly.
Once the databases are successfully upgraded, continue with the steps after 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.
Important
After you apply the upgrade, clear your browser cache before you open the website or Kentico administration interface.
You need to update your code according to the new API of Kentico 12, including:
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 (opens in a new tab)
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 (opens in a new tab) 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:
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:
Open your Kentico project in Visual Studio.
Open the Package Manager Console (under Tools > NuGet Package Manager).
Run the following commands:
Uninstall-Package -Id Rx-Main -Force -RemoveDependencies;
Uninstall-Package -Id linqtotwitter -Force;
Update-Package -reinstall;
Install-Package -Id linqtotwitter -Version 4.0.0The Update-Package (opens in a new tab) 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.
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.
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.
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.
Kentico 12 brings the following assembly changes:
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.
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 (opens in a new tab) testing framework or to work without the CMS.Tests library.
For more information, see the Writing automated tests chapter.
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:
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:
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:
You need to add Kentico version 12 licenses for the domains used by your sites:
To ensure that macros and the administration interface work correctly after the upgrade:
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:
For more information, see the Macro expressions chapter.
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.
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:
The geolocation feature was updated to work with Maxmind's GeoIP2 Databases (opens in a new tab).
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.
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.).
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:
In both cases, a binding redirect (opens in a new tab) 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).
Click Next to start the upgrade procedure.
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):
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: