Upgrading to Kentico 12

Upgrading to Kentico 12

Steps before you start the upgrade

Custom code analysis

 

See the Release notes for highlights of the breaking changes in the Kentico 12 API.

If you have an MVC site or if your Kentico 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 code that is no longer valid in version 12
• Provides recommendations for each occurrence of invalid code
• Can automatically convert the majority of code to the Kentico 12 API

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

Required .NET Compiler Platform

Kentico 12 requires the .NET Compiler Platform ("Roslyn") compiler to run, provided by the Microsoft.CodeDom.Providers.DotNetCompilerPlatform NuGet package. The upgrade automatically updates the package to version 2.0.1 (if necessary).

The updated version no longer requires the Microsoft.Net.Compilers package as a dependency, and we recommend uninstalling this package (unless required by your custom functionality).

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.

 

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.

Macro security

需要用macro重新签名

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

Removed web parts

The upgrade removes the following web parts:

• Friends list
• Friends viewer
• Friends waiting for approval
• Friendship management
• My friends
• My pending requests
• Rejected friends
• Request friendship
• Contact list
• Ignore list
• Inbox
• Messaging info panel
• My messages
• Outbox
• Send message

You need to replace or remove instances of these web parts on your site's page templates. Use the following process:

1. Open the Web parts application.
2. Select the given web part and view the Usage tab.
3. Remove or replace any occurrences of the web part on your site.
4. If a web part is used by a widget or inherited web part, perform these steps for the given components (use the Widgets application for widgets).

After you remove or replace all occurrences of a web part, we strongly recommend that you delete it in the Web parts application.

 

The upgrade procedure deletes all source files of the listed web parts, but leaves their database records. If you do not manually delete them, these non-functional web parts and their categories may remain in your database after the upgrade, with a (Removed) suffix added to the display name.

Removed goo.gl URL shortener integration

The upgrade removes the goo.gl URL shortener for social media posts from the system. The Google URL Shortener service is discontinued and its API will stop working after March 30, 2019.

Before starting the upgrade, make sure that the goo.gl URL shortener is not used:

• In the Settings application, check the Social marketing -> Default URL shortener settings. If necessary, switch to a different URL shortener or select the (do not shorten links) option.
• In the Workflows application, check any advanced workflows that contain Publish to Facebook, Publish to Twitter or Publish to LinkedIn steps. If necessary, edit the steps and switch their URL shortener property to a different shortener or select the (do not shorten links) option.

If you do not remove usage of the goo.gl URL shortener from your system, you may encounter errors when posting to social media after the upgrade.

Applying the upgrade

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

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

Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Kentico 12 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 12, 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 12 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 12 remain in the file system, with an added .deleted extension. These files 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:
    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.

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.

 

Important

After you apply the upgrade, clear your browser cache before you open the website or Kentico administration interface.

Kentico 12 setup files

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

To obtain the installer and setup files for Kentico 12:

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

Licenses

You need to add Kentico version 12 licenses for the domains used by your sites:

1. In the Kentico administration interface, open the Licenses application.
2. Delete the old version 11 licenses.
3. Click New license to add your licenses for version 12.

Running the website - First request

Open the upgraded website in a browser. For MVC sites, you need to open the URL of the Kentico administration interface (not the live site presented by the MVC application).

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.

Important: 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_110_120.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.