Upgrading to Kentico 8.1

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

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.1. See Server and hosting requirements for details.

You can upgrade from any type of Kentico 8 project, including all hotfix versions.

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

• Kentico 8.1 updates the document terminology — the word Document is replaced by Page in the administration interface. This affects the names of applications, web parts, and other related text. Code names and API keywords remain unchanged.
• 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.1 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.1 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

• The Shopping cart contains product order rule for order discount and free shipping offer conditions is now obsolete.

  • Existing discounts keep the rule and continue to work after the upgrade, but the rule is disabled for new discounts.
  • For new rules, you can use the new Shopping cart contains products order rule with options All and Any.
  • To allow the obsolete rule for new discounts, go to Store configuration -> Discount rules -> Order rules, edit the rule and enable it.

• The Bundle items selector form control is now obsolete.

  • To create fields for selecting which products belong to a bundle, use the Multiple object binding control form control and set the Binding object type to ecommerce.bundle.

LinkedIn integration

• The LinkedIn apply with web part was removed (LinkedIn no longer supports this functionality).

Installing the upgrade procedure

1. Download the Kentico 8.1 upgrade.
2. Run Upgrade_8_0_8_1.exe.
3. Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\8.1\Upgrade80_81 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.1
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Kentico 8.1 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.

Separated on-line marketing database

The upgrade is NOT supported for instances with a separated on-line marketing database. In this case, you need to rejoin the database before starting the upgrade procedure. You can perform the separation again after the upgrade is complete.

See also: Separating the contact management database

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

   Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Kentico 8.1 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.

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.1, 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 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 Kentico 8.1 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.1 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.

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.1, 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.1 setup files

The upgrade converts your web projects to version 8.1, 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.1 web projects.

To obtain the installer and setup files for Kentico 8.1:

1. Download the Kentico 8.1 installer.
2. Run Kentico_8_1.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

Open the upgraded website in a browser. When handling the first request, the system performs certain tasks required to finalize the upgrade. This includes the import of new objects. Processing of the first request may take longer than usual.

Object import

The upgrade procedure automatically imports new web part, widget, report and time zone objects. Once the upgrade is finished, please check the system’s Event log for any import errors between the Upgrade - Start and Upgrade - Finish events.

If you find import-related errors, open the Sites application, click Import site or objects and try to import the upgrade_80_81.zip package manually.

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.

SharePoint integration

The upgrade installs the new SharePoint module by default. See Integrating SharePoint for more information.

If you plan to use the new module:

1. In the Kentico administration interface, open the Modules application.
2. Edit the SharePoint module.
3. Select the Sites tab and add your sites.

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.

File uploader styling

Kentico 8.1 uses a new file uploader based on HTML5 instead of the Silverlight uploader from previous versions. The new uploader has modified HTML markup that applies a different CSS class.

You may need to update your site’s stylesheet after the upgrade if you use custom live site styling without linking the default Skin.css file (see Designing websites using CSS for more information). To style the uploader in your own stylesheet, define the following classes:

.uploader-overlay-div {
  background: rgba(0, 0, 0, 0);
  overflow: hidden;
  opacity: 0;
  width: 100%;
  height: 100%;
  position: absolute;
  top: 0;
  left: 0;
}

.uploader-overlay-div > input[type="file"] {
  display: none;
}

You can adjust the styles of the classes to match the design of your website.