Upgrading to Kentico 8.2

This page provides instructions for upgrading Kentico projects from version 8.1 to 8.2.

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

Prerequisites

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, GlobalAssemblyInfo.cs, the CMS and Lib 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.

Upgrading across multiple versions

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.

Upgrade overview

The following is a summary of the most important changes that the upgrade performs.

• 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 8.2 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 8.2 remain in the file system (but are not included in the CMSApp project in web application projects).
• The upgrade disables web farm functionality. You can re-enable web farms 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 version 8 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).

E-commerce

• Global shipping options are replaced with site shipping options.

  • Existing global shipping options are transformed to site shipping options and copied to every site.

    • Options are transformed completely except for:
      • Teaser images of the shipping options – if you don’t have access to the teaser image files, download them from the system before the upgrade.
      • Values of custom fields of shipping options – if you created custom fields in the Ecommerce.ShippingOption class, you need to set their values manually in the new site shipping options.

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

Email marketing

• The Newsletters application (and module) is renamed to Email marketing.

SharePoint integration

• The upgrade adds a new SharePoint application, which allows management of SharePoint libraries.
• The original SharePoint application is renamed to SharePoint connections.

Installing the upgrade procedure

1. Download the Kentico 8.2 upgrade.
2. Run Upgrade_8_1_8_2.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\8.2\Upgrade81_82 folder by default).

Steps before you start the upgrade

Custom code analysis

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 page on the DevNet portal. See Upgrading custom code to learn more.

The tool has the following functionality:

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

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

Database schema when using a database connection with Windows authentication

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

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.

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.

Applying the upgrade

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

1. Open the folder where you installed the upgrade.

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

3. Enter the path to your Kentico 8.1 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 haven’t done so already.

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

   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. 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 8.2, 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 doesn’t 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 8.2 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 8.2 remain in the file system (but 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:
    • Edit the new web.config and transfer over any customizations and the connection string from the original web.config.
    • Move your original web.config to a different location.
    • Rename web.config.new to web.config.

Close the upgrade utility.

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\8.2\Upgrade81_82 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 custom code according to the new API of Kentico 8.2, including:

• Custom or customized code files in the web project
• Virtual objects in Kentico, such as transformations and page layouts

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.

Kentico 8.2 setup files

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:

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

Merging web.config probing elements

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.

1. Open the project’s web.config file.

2. Merge the value of the new <probing> element with the existing one.

   Copy

   
   
   
    <probing privatePath="ExistingPath;CMSDependencies\Newtonsoft.Json.4.5.0.0" xmlns="urn:schemas-microsoft-com:asm.v1" />
   
   
    

3. Save the web.config file.

Using Newtonsoft.Json with Kentico

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 package into the given projects as a replacement.

Using ASP.NET Web API with Kentico

You should now use the Microsoft.AspNet.WebApi Nuget package in projects where you use Web API. See Using ASP.NET Web API with Kentico for more information.

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

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:

• If you find errors related to the object import, open the Sites application, click Import site or objectsand try to import the upgrade_81_82.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.

Macros

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

1. Log 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, you need to manually enable web farms after you complete the upgrade.

1. In the Kentico administration interface, open the Settings application.
2. Expand the Versioning & Synchronization -> Web farm category.
3. Check the Enable web farm setting.
4. Click Save.

Marketing automation

The ‘Property name’ value in the ‘Set contact property’ action displays unnecessary values. To hide the columns:

1. Open the Marketing automation application.
2. Switch to Actions.
3. Edit the Set contact property action.
4. Switch to Parameters.
5. Under Editing control settings, disable Show all columns.