Upgrading to Xperience 13

This page provides instructions for upgrading projects from version Kentico 12 Service Pack to Xperience 13.

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 administration and live site projects
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 following:

• All system requirements of Xperience 13.
  • Note: Microsoft SQL Server 2008 R2 is no longer supported for Xperience databases. You need to upgrade your database server (and database compatibility level) to version 2012 or newer before you start the Xperience upgrade.
• The machine where you perform the upgrade must have a working Internet connection.
• Xperience 13 only supports the MVC and ASP.NET Core development models. Upgrading Portal Engine sites is not possible.
• The upgrade to Xperience 13 is not supported for projects of the web site type. In these cases, only run the database upgrade scripts, then install a new Xperience 13 project and manually transfer any customizations (or convert your administration project to a web application).
• The upgrade does not support installations with removed (separated) modules. To perform the upgrade, you need to use the Kentico 12 Service Pack installer utility to add any missing modules.
• The upgrade is not possible if the project contains obsolete forms that are not based on the MVC Form builder (forms created in Kentico version 11 or older). In these cases, you need to back up any recorded form data and remove the forms. You can create a new form based on the MVC Form builder and migrate the data.

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.

Upgrading across multiple versions

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 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.

• 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.

  • Web parts can no longer be used to build website pages. They remain in the system as components for administration interface pages.
  • Portal Engine page templates can no longer be assigned to website pages. They remain in the system as a way to build administration interface pages. Ad-hoc templates dedicated to individual pages are no longer supported. When upgrading projects, all page templates except for UI and dashboard templates are removed, and any ad-hoc UI templates are converted to global shared templates.
  • All support for the original Portal Engine widgets was removed for live site content. This includes editor, user and group widgets, as well as inline widgets (adding widgets into editable text areas via the editor). Widgets can still be used on dashboards within the administration interface.

• 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 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 Xperience 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 Xperience 13 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 Xperience 13 remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project.

• 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.

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

• Xperience 13 no longer contains functionality for files represented as pages in the content tree via the CMS.File page type. The upgrade preserves the CMS.File page type and any existing pages. However, there is no longer any “special system handling” for CMS.File pages and they behave as standard pages with file attachments.
• Due to the removal of community features and groups, all group media libraries are converted to regular media libraries by the upgrade.

On-line marketing

• Marketing automation – the upgrade makes the following changes for steps within existing marketing automation processes:
  • Standard – renamed to Approve progress.
  • First win – renamed to If/Else.
  • Condition – automatically converted to steps of the If/Else type.
  • Multi-choice – existing occurrences remain in processes, but are considered as obsolete. Can no longer be added directly, but existing steps can be cloned. We recommend using the If/Else step type to create automatic branching conditions.
  • User choice – renamed to Manual choice.
  • Start process – renamed to Start another process.

Email templates

• The upgrade removes the Membership - Forgotten password (obsolete) email template, the related macro resolver, and the Forgotten password template type. This template was obsolete and no longer used by the system’s password reset functionality. Any custom email templates assigned to the Forgotten password template type remain in the system, but macros that rely on the removed resolver will no longer work correctly. Such templates are marked with the “(obsolete)” suffix in their display name.

Social & Community

• The upgrade removes the following community features from the system, along with all related components (web parts, widgets, email templates, form controls, settings) and API:
  • Abuse report
  • Bad words
  • Blogs
  • Chat
  • Content rating
  • Events
  • Forums
  • Flood protection
  • Groups
  • Message boards
  • Polls
  • User badges and activity points
  • User contribution web parts

Installing the upgrade procedure

1. Download the Xperience 13 upgrade.
2. Run Upgrade_12_0_13_0.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\13.0\Upgrade120_130 folder by default).

Steps before you start the upgrade

Custom code analysis

We strongly recommend using the Xperience 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 Xperience 13
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Xperience 13 API

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

Required .NET Compiler Platform

Xperience 13 requires the .NET Compiler Platform (Roslyn) compiler to run, provided by the Microsoft.CodeDom.Providers.DotNetCompilerPlatform NuGet package.

Removed Portal Engine functionality

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.

• All Portal Engine page templates except for UI and dashboard templates. Any ad-hoc UI templates are converted to global shared templates.
• Transformations of ASCX, XSLT, and jQuery types. You can create equivalent macro-based transformations if necessary.
• Device profiles and device profile layouts.

Alternative URLs

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.

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 Xperience database tables

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.

Applying the upgrade

Upgrading the administration project

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 12 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).

6. 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.

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 Xperience 13 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 Xperience 13remain in the file system, with an added .deleted extension. These files are not included in the CMSApp project.

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.

11. Hotfix the project to the latest hotfix version.

12. 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.

13. Rebuild the project.

Close the upgrade utility.

Upgrading MVC projects

You also need to upgrade the Xperience code used by the MVC application that provides your live site:

1. Open your MVC application in Visual Studio.
2. Update your MVC project’s Target framework version to NET Framework 4.8.
3. Right-click your MVC project in the Solution Explorer and select Manage NuGet Packages.
4. Uninstall all Kentico 12 integration packages for MVC development – Kentico.AspNet.Mvc, etc.
5. Install the Kentico.Xperience.AspNet.Mvc5 NuGet package (use version 13.0.0 until you apply a hotfix to your upgraded Xperience project).
6. Clean your project’s output folder (~/bin/ by default).
7. Rebuild the solution.

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\13.0\Upgrade120_130 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 Xperience 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 Xperience 13, including:

• Code files in MVC projects that use the Xperience API
• Custom or customized code files in the Xperience web project

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

NuGet package updates

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.

External authentication packages

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.

Consolidation of administration NuGet packages

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 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 Xperience CMSApp web project.

If you update the Target framework version for a project, we also recommend consolidating all installed NuGet packages to target the same version:

1. In Visual Studio, open the Package Manager Console (under Tools > NuGet Package Manager).

2. 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.

Assembly references

Xperience 13 brings the following assembly changes:

• ThoughtWorks.QRCode.dll removed
• CMS.PortalEngine.dll and CMS.OutputFilter.dll merged into CMS.PortalEngine.Web.UI.dll

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.

Xperience 13 setup files

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:

1. Download the Xperience 13 installer (this installer includes Refresh 12, i.e. hotfix version 13.0.142).
2. Run Xperience_13_Refresh12.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. 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:

• If you find errors related to the object import, open the Sites application, click Import site or objects and try to import the upgrade_120_130.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 Xperience 13 licenses for the domains used by your sites:

1. In the Xperience administration interface, open the License keys application.
2. Delete the old version 12 licenses.
3. Click New license to add your licenses for version 13.

Macros

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

1. Sign in to the Xperience 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.

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.

Web farms

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.

1. In the Xperience administration interface, open the Settings application.
2. Expand the Versioning & Synchronization -> Web farm category.
3. Select the Web farm mode:
   • Automatic (recommended) – 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.

Switching to content tree-based routing

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.

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\13.0\Upgrade120_130 by default), and copy the CMS\CMS\CMSSiteUtils\Import\Upgrade_120_130.zip file into the CMS\CMSSiteUtils\Import folder of the new Xperience 13 project.
7. Perform all relevant steps after the upgrade.