Is this really the version you are looking for? Kentico Xperience 8.2 Documentation is no longer updated. Use the switcher in the header to choose your product version.
This page provides instructions for upgrading Kentico projects from version 8.1 to 8.2.
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.
Microsoft Azure projects
If you are upgrading a project hosted on Microsoft Azure, please follow the instructions on the Upgrading Microsoft Azure projects page.
Before you start the upgrade, please make sure that your environment fulfills the requirements of Kentico 8.2. See Server and hosting requirements for details.
Note: The upgrade must be applied to complete projects that use the standard folder structure (the solution file, , the and sub-folders). 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 8.1, 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. During the first request after the upgrade, the system performs certain tasks required to finish the upgrade, including the import of new objects.
The following is a summary of the most important changes that the upgrade performs.
This does not include all Kentico 8.2 features and changes – see Release notes - Kentico 8 versions for a comprehensive list.
Global shipping options are replaced with site shipping options.
Existing global shipping options are transformed to site shipping options and copied to every site.
If the site main currency is different from the global main currency, shipping charges and costs are converted to the site default currency according to the site exchange rate table.
Since global shipping options are not supported anymore, you cannot configure shipping in the Multistore configuration application.
For a list of breaking changes in the Kentico 8.2 API, see the Release notes.
If your 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 code upgrade tool’s output will help you update your custom code after you perform the upgrade.
If your Kentico project uses Windows authentication (integrated security) for its database connection, the database upgrade scripts run under the current Windows account, i.e. the user who runs the upgrade utility.
To avoid errors during the upgrade, you need to make sure that the corresponding database user has the same Default schema value as the schema of the objects in your Kentico database (dbo by default).
You can check the database authentication settings in the connection string within your project's web.config file.
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:
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.
We strongly recommend using the Kentico Upgrade Utility to perform the upgrade automatically.
Manual upgrade
If you cannot perform the upgrade automatically (for example when you cannot directly access the environment hosting the Kentico instance), you can perform the upgrade manually.
Open the folder where you installed the upgrade.
Run the Kentico Upgrade Utility (Upgrade.exe).
Enter the path to your Kentico 8.1 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 haven’t done so already.
Select whether you want to upgrade files, 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 8.2 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.
Close the upgrade utility.
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\8.2\Upgrade81_82 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 custom code according to the new API of Kentico 8.2, including:
Use the output of the Kentico code upgrade tool (described in Custom code analysis) to find occurrences of invalid code and recommendations on how to fix or replace them.
Tip: 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 converts your web projects to version 8.2, 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 8.2 web projects.
To obtain the installer and setup files for Kentico 8.2:
The 8.2 upgrade adds a new <probing> element to the project's web.config file. The new element specifies the 'CMSDependencies\Newtonsoft.Json.4.5.0.0' base subdirectory. If you use your own <probing> element, you need to merge the 'privatePath' values into a single element.
Open the project's web.config file.
Merge the value of the new <probing> element with the existing one.
<probing privatePath="ExistingPath;CMSDependencies\Newtonsoft.Json.4.5.0.0" xmlns="urn:schemas-microsoft-com:asm.v1" />Save the web.config file.
Kentico no longer contains the Newtonsoft.Json library in the Lib folder. If you have any custom code that requires the library, install the Newtonsoft.Json NuGet (opens in a new tab) package into the given projects as a replacement.
You should now use the Microsoft.AspNet.WebApi Nuget (opens in a new tab) package in projects where you use Web API. See Using ASP.NET Web API with Kentico for more information.
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:
Open the upgraded website in a browser. When handling the first request, 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.
Important: Once the website loads, log 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:
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, you need to manually enable web farms after you complete the upgrade.
The 'Property name' value in the 'Set contact property' action displays unnecessary values. To hide the columns: