Xperience 13 Refresh releases
If you already have Xperience 13 and wish to apply a Refresh release, do NOT follow the upgrade process described on this page.
You only need to apply the appropriate hotfix version to your project. See the Hotfix instructions to learn how to install Refreshes via the hotfix.
This page provides instructions for upgrading projects from version Kentico 12 Service Pack to Xperience 13.
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 following:
Note: The upgrade must be applied to complete administration 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 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 12, 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 Xperience 13 features and changes – see Release notes - Xperience 13 for a comprehensive list.
The Portal Engine and ASPX template development models for websites are no longer supported. Related features and components (web parts, widgets, page templates, controls, etc.) are removed from the system.
If your project's Target framework version is lower than NET Framework 4.8, the upgrade sets the version to 4.8 (the minimum .NET version supported by Xperience 13).
The upgrade integrates third-party libraries by installing and updating NuGet packages (and their dependencies) in the Xperience 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 (opens in a new tab) 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).
Custom files in the original project are transferred to the upgraded project.
Customized Xperience files are preserved (does not apply if you choose to overwrite all files when applying the upgrade):
If your Xperience 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 Xperience database (dbo by default).
The upgrade disables web farm and continuous integration functionality. You can re-enable the features after you complete the upgrade.
See the Release notes for highlights of the breaking changes in the Xperience 13 API.
We strongly recommend using the Xperience 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.
Xperience 13 requires the .NET Compiler Platform ( (opens in a new tab) compiler to run, provided by the Microsoft.CodeDom.Providers.DotNetCompilerPlatform (opens in a new tab) NuGet package.
Due to the removal of the Portal Engine development model for live site pages, the upgrade removes the following objects and functionality. We recommend that you back up any relevant code or data that you store in the objects, since it will be deleted after the upgrade.
The maximum length of alternative URLs was reduced to 400 characters. You need to manually shorten all alternative URLs longer than 400 characters before performing the upgrade. The presence of longer alternative URLs will cause the upgrade process to fail.
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 -> 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 Xperience 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.
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 Xperience 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 12 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:
Click Switch to advanced mode and disable the Rebuild web project option. This is necessary because the project could contain certain files (introduced by later K12 hotfixes) that will not be compilable immediately after the upgrade is applied.
Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Xperience 13 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.
Choose a method of taking the project offline and bringing it back online.
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:
If your project contains custom code that is no longer supported in Xperience 13, you need to resolve these code changes before rebuilding the project.
Rebuild your administration project.
Close the upgrade utility.
You also need to upgrade the Xperience code used by the MVC application that provides your live site:
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\13.0\Upgrade120_130 by default).
Expand the SQL\Separation folder.
Manually run the script files in the following order:
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 Xperience administration interface.
You need to update your code according to the new API of Xperience 13, including:
Use the output of the Xperience code upgrade tool to find occurrences of invalid code and recommendations on how to fix or replace them.
You can also search for specific API resolutions on the DevNet portal (opens in a new tab)
All NuGet packages used for MVC development and general integration of the Xperience API were renamed (rebranded). When upgrading MVC projects, custom assemblies, or any external applications that use the packages, you need to uninstall the original Kentico 12 packages and replace them with the equivalent packages for Xperience 13.
Kentico 12 | Xperience 13 |
|---|---|
Kentico.AspNet.Mvc | Kentico.Xperience.AspNet.Mvc5 |
Kentico.AspNet.Mvc.Libraries | Kentico.Xperience.AspNet.Mvc5.Libraries |
Kentico.Libraries | Kentico.Xperience.Libraries |
Kentico.Libraries.Web.UI | The package was removed. The contained Web.UI libraries are only intended for use within the Xperience administration application. If necessary, you can access the libraries in the Lib folder of Xperience projects. |
Kentico.LanguagePack.English | The package was removed. Localization files are now part of application assemblies (included as part of the Kentico.Xperience.AspNet.Mvc5.Libraries package). |
Kentico.Libraries.Tests | Kentico.Xperience.Libraries.Tests |
Kentico.Glimpse | Kentico.Xperience.Glimpse |
If your live site project uses external authentication and the Microsoft.Owin.Security NuGet packages that provide the required middleware components, you need to update these packages to version 4.0.0 or newer. Older versions are not compatible with Xperience 13.
The upgrade updates the version of some of the NuGet packages installed within the Xperience administration 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 you update the Target framework version for a project, we also recommend consolidating all installed NuGet packages to target the same version:
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.
Xperience 13 brings the following assembly changes:
You need to remove any manually added references from custom projects to removed 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 upgrade converts your web projects to version 13, but does not provide the associated setup files (i.e. the Xperience program files that are separate from individual web projects). The setup files contain external utilities, sample files, and allow you to install new Xperience 13 web projects.
To obtain the installer and setup files for Xperience 13:
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. You need to open the URL of the Xperience administration interface (not the live site).
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 Xperience 13 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:
After the upgrade, certain macros in the system may be moved or marked obsolete. Follow the instruction provided by the macro report tool to resolve the identified issues. If a macro method is reported as removed, and you wish to continue using it, you need to develop your own custom implementation.
For more information, see the Macro expressions chapter.
The upgrade procedure automatically disables web farm functionality. You need to enable web farms again after you complete the upgrade.
We recommend that you enable the web farm on one server or instance and after that add the remaining servers to the web farm.
Content tree-based routing is a new Xperience feature that enables automatic generation of URLs for pages based on their position in the content tree. Another new feature, managed through the Former URLs application, enables automatic tracking of changes made to the URL paths of pages in the content tree and handles redirection from the pages' old URLs to the current URLs.
If you want to enable content tree-based routing on a site that uses customrouting based on page type URL patterns, you can manually preserve the old URLs as former URLs by running a prepared code snippet. This ensures that pages remain accessible under their old URLs and allows for a smoother transition to the new routing type.
See Enabling content tree-based routing for more information.
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.).
After you finish upgrading to version 13.0.0, update the project to the latest hotfix version.
Xperience 13 has a large number of released refreshes and hotfixes, which add many new features and ensure that the application is secure.
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: