Upgrading to Kentico 9

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

Upgrading non-standard projects

If you are upgrading a project hosted on Microsoft Azure, please follow the instructions on the Upgrading Microsoft Azure projects page.
If you are upgrading a source code instance, see Upgrading source code instances for a general outline of the recommended process.

Check the prerequisites and Upgrade overview
Install the upgrade procedure
Perform the required steps before the upgrade
Apply the upgrade to your Kentico project
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 requirements of Kentico 9. 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.2, 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. 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.

This does not include all Kentico 9 features and changes – see Release notes - Kentico 9 for a comprehensive list.

If your project uses .NET Framework 4.0, the upgrade sets the project’s version to 4.5 (the minimum version supported by Kentico 9).
The upgrade automatically applies hotfix 9.0.1 (you may need to download and install the latest Kentico 9 upgrade package).
The Project management feature and multiple other web parts and widgets (for example the Document library and Drop-down menu) are removed and their development is discontinued. However, we provide means of recovering them after the upgrade – see Recovering abandoned features, web parts and widgets for details.
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 9 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 9 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. Web farm functionality was redesigned and the original web farm synchronization mechanisms are no longer available. See Settings - Web farm and Configuring web farm servers for details.

Class fields

The upgrade overwrites the form definitions of the default fields of system classes and their alternative forms. Custom fields from version 8.2 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

The upgrade removes View_COM_SKU and all page related views with the exception of View_CMS_Tree_Joined, which is used as the base for querying of page data.See the breaking changes section of our release notes for more information.
The upgrade removes the SiteName, NodeOwnerFullName, NodeOwnerUserName, NodeOwnerEmail and Published columns from the database view used to load page data.

E-commerce

Flat tax classes (tax classes with a fixed tax) are no longer supported.
- The upgrade removes existing flat taxes.
- Import packages containing flat taxes will be imported without these taxes.
Legacy field mapping of product page types for backward compatibility is no longer supported.
- There is no alternative for the legacy mapping. See Mapping product type database columns to learn more information about field mapping.

On-line marketing

Creating a new contact when merging contacts is no longer supported.
- If you have the Create a new contact option set in the Settings -> On-line marketing -> Contact management -> Global data & merging -> When a visitor has more contacts, use setting, the upgrade changes the value to Last active contact.
- Email marketing now uses a different database structure.
- The upgrade modifies the Newsletter_OpenedEmail table, which stores the opened email records.
- Clicked link records are moved from the Newsletter_SubscriberLink table to the new Newsletter_ClickedLink table.
- Activities in the OM_Activity database table that record opened emails and clicked links by users are copied to the Newsletter_OpenedEmail table or the Newsletter_ClickedLink table respectively.
- Clicked links: If you have a separated database for on-line marketing, subscribers are temporarily copied to the separated database and the separated database may temporarily need more space.
- Opened emails: Every email can have only one opened email record. If there are more activities related to one opened email, the other records are not copied to the Newsletter_OpenedEmail table.
- The first load of the website after the upgrade then finishes the transition of the data (e.g., adds emails to the clicked links or opened emails).
Existing marketing campaigns
The Campaign tracking URL parameter setting was removed and now the standardized utm_campaign query string parameter is used in the URL by default.
- Campaign tracking for existing links with different parameters in the URLs will no longer work after the upgrade.

Installing the upgrade procedure

Download the Kentico 9 upgrade.
Run Upgrade_8_2_9_0.exe.
Install the upgrade procedure (the installer places the upgrade into the C:\Program Files\Kentico\9.0\Upgrade82_90 folder by default).

Steps before you start the upgrade

Custom code analysis

For a list of breaking changes in the Kentico 9 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 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 9
Provides recommendations for each occurrence of invalid code
Can automatically convert the majority of code to the Kentico 9 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).

You can check the database authentication settings in the connection string within your project’s web.config file.

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:

Recover any data that you wish to use after the upgrade.
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:

In the System application, select the Macros -> Report tab.
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.

E-commerce

Flat tax classes (tax classes with a fixed tax) are no longer supported. If you apply flat taxes to shipping costs, implement a custom shipping carrier provider to replace flat taxes and to achieve the same result.

Obsolete macros in the ##MACRONAME## format are no longer supported. To replace the obsolete macros, use equivalent supported macros according to the following table:

Old macro	New macro
##INVOICENUMBER##	{% Order.OrderInvoiceNumber %}
##ORDERDATE##	{% Format(Order.OrderDate, “{0:d}”) %}
##ORDERNOTE##	{% HTMLEncode(Order.OrderNote) %}
##BILLINGADDRESS##	{% BillingAddress.ApplyTransformation(“Ecommerce.Transformations.Order_Address”) %} + tweak transformation appearance
##SHIPPINGADDRESS##	{% ShippingAddress.ApplyTransformation(“Ecommerce.Transformations.Order_Address”) %} + tweak transformation appearance
##PAYMENTOPTION##	{% HTMLEncode(PaymentOption.PaymentOptionDisplayName) %}
##SHIPPINGOPTION##	{% HTMLEncode(ShippingOption.ShippingOptionDisplayName) %}
##PRODUCTLIST##	{% ContentTable.ApplyTransformation(“Ecommerce.Transformations.Order_ContentTable”, “Ecommerce.Transformations.Order_ContentTableHeader”, “Ecommerce.Transformations.Order_ContentTableFooter”) %} + tweak transformation appearance
##TAXRECAPITULATION##	{% ContentTaxesTable.ApplyTransformation(“Ecommerce.Transformations.Order_TaxesTable”, “Ecommerce.Transformations.Order_TaxesTableHeader”, “Ecommerce.Transformations.Order_TaxesTableFooter”) %} + tweak transformation appearance
##TOTALPRICE##	{% TotalPrice.Format(Currency.CurrencyFormatString) %}
##TOTALSHIPPING##	{% TotalShipping.Format(Currency.CurrencyFormatString) %}
##COMPANYADDRESS##	<span class=“InvoiceCompanyAddressTitle”>{$ Ecommerce.Invoice.CompanyAddressTitle $ }</span>{% CompanyAddress.ApplyTransformation(“Ecommerce.Transformations.Order_Address”) %} + tweak transformation appearance
##TAXREGISTRATIONID##	{% Customer.CustomerTaxRegistrationID %}
##ORGANIZATIONID##	{% Customer.CustomerOrganizationID %}
##applicationurl##	{% Transformation.GetAbsoluteUrl(“~/”).TrimEnd(“/”) %}
##NEWORDERLINK##	<a href=“{% UIContext.GetElementUrl(”CMS.Ecommerce”, “OrderProperties”, true, Order.OrderID) %}” target=“_blank”>{$ Ecommerce.OrderNotification.OpenOrder $}</a></p></td></tr><tr style="background-color: white;"><td><p>##paymentreceivedtext##</p></td><td><p>{$ OrderPaymentNotificationToCustomer.PaymentReceived $}</p></td></tr><tr style="background-color: white;"><td><p>##thankyoutext##</p></td><td><p>{$ OrderNotification.ThankYouText $}

The upgrade removes the obsolete Shopping cart preview web part. To replace the web part, see Displaying the shopping cart preview on pages.
The upgrade removes the obsolete Product filter web part. To replace the web part, see Configuring product listings with filtering.
The upgrade removes the E-commerce settings checker widget. Remove the widget from user dashboards in the Store overviewapplication or inform your users to remove the widget from their dashboards.

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.

Large on-line marketing databases

If you have more than 1 million records in the Newsletter_OpenedEmail or Newsletter_SubscriberLink database tables, the upgrade procedure could take more time than expected (likely within minutes) and the database could temporarily require more space (due to copying of the records). We recommend that you increase your database connection timeout using theConnection stringin the web.config.

Removing the MVC_App project

If you are not using the CMSApp_MVC project for your MVC development, we recommend removing the project from the solution. We now recommend a different approach for developing MVC sites.

Page attachment history

Kentico 9 allows storing of page attachment history in the file system. This allows you to lower the overall size of the system database. The settings are shared with published versions of attachments. Based on the value in the Store files in setting in Settings -> System -> Files, the system may start saving new attachment history to the file system after the upgrade, while keeping the old history in the database.

We recommend storing page attachment history on the file system.

If you want to keep storing attachment history in the database, add the following key into the appSettings section of your application’s web.config file:




 <add key="CMSForceAttachmentHistoryInDatabase" value="true" />

Applying the upgrade

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.

See Upgrading Kentico manually.

Open the folder where you installed the upgrade.
Run the Kentico Upgrade Utility (Upgrade.exe).
Enter the path to your Kentico 8.2 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, 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).
Warning: If you enable the Overwrite all files option in advanced mode, the upgrade replaces all project files with the default Kentico 9 files, regardless of customizations. This includes the web.config file, which you need to configure again after applying the upgrade.
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 9, 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.
Choose a method of taking the project offline and bringing it back online.
Click Next to start the upgrade procedure.
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 9 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 9 remain in the file system (but are not included in the CMSApp project in web application projects).
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:

Open the upgrade installation directory (C:\Program Files\Kentico\9.0\Upgrade82_90 by default).
Expand the SQL\Separation folder.
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)

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.

Workaround for separated databases without marketing emails

If your separated on-line marketing database does not contain any marketing emails (under email campaigns), an error will occur when running the first request after the upgrade and the finalization of the upgrade procedure will not finish.

To work around this problem, manually perform the following steps before you open the upgraded site in a browser:

Open the upgraded project in Visual Studio.
Expand the App_Code (for web site projects) or Old_App_Code folder (for web application projects), and edit the CMS\UpgradeProcedure.cs file.

Comment out the following code that executes queries related to marketing emails (line 1136 by default):




 // Update the data in ClickedLink/OpenedEmail table using OM connection string (or default)
 /*using (new CMSConnectionScope(DatabaseSeparationHelper.OM_CONNECTION_STRING, false, true))
 {
     ConnectionHelper.ExecuteQuery(updateClicksScript, null, QueryTypeEnum.SQLQuery);
     ConnectionHelper.ExecuteQuery(updateOpensScript, null, QueryTypeEnum.SQLQuery);
     ConnectionHelper.ExecuteQuery(deleteOpensWithNonExistingIssues, null, QueryTypeEnum.SQLQuery);
 }*/

Save the changes.
If you have a web application project type, build the CMSApp project (you may first need to resolve API changes in custom code – see 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.

Important

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

API changes

You need to update your custom code according to the new API of Kentico 9, 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 9 setup files

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

To obtain the installer and setup files for Kentico 9:

Download the Kentico 9 installer.
Run Kentico_9_0.exe.
Read and accept the License Terms and Conditions and click Custom installation.
Select Install only program files and click Install.

Customizing the mimetypes.txt file

If you made any customizations to the mimetypes.txt file located in ‘_{CMSAdminControls/mimetypes.txt’, you need to move the customizations to the same file in ’}/App_Data’.

URL routes with custom extensions

The upgraded web.config file no longer registers UrlRoutingModule for handling of non-managed requests. As a result, the application only processes URL routes that are extensionless or have the .aspx extension by default.

On Kentico sites, URL routing can be used in the following ways:

Within page URL paths of the Route or MVC type. Configured in the Pages application on the Properties -> URLs tab.
Routes registered using custom code (typically within application start code).

If your website uses URL routes with custom extensions, you need to enable processing of all requests by managed modules:

Edit your application’s web.config file.
Find the <modules> element inside the system.webServer section directly under the web.config root (i.e. not under a specific <location> element).

Set the runAllManagedModulesForAllRequests attribute to true for the opening <modules> tag:




 <system.webServer>
   ...
   <modules runAllManagedModulesForAllRequests="true">
 ...
 </system.webServer>

Projects with a Classic application pool

Kentico 9 no longer supports Application Pools with Managed Pipeline Mode set to Classic. If your application originally used Classic mode, you need to switch to Integrated mode after performing the upgrade:

Run Internet Information Services (IIS) Manager in Windows.
Select the Application Pool used by your application and click Basic settings.
Switch the Managed pipeline mode to Integrated and click OK.
Edit your project’s web.config file.
Add the following <validation> element inside the system.webServer section directly under the web.config root (i.e. not under a specific <location> element):
```
 <validation validateIntegratedModeConfiguration="false" />


 
```

You may also need to adjust or remove any custom parts of your application that rely on Classic application pool mode.

Using the CMSApp_MVC project after the upgrade

If you plan on using the CMSApp_MVC project for your MVC development after upgrading to Kentico 9, you need to:

Add the CMSApp_MVC project into the solution.
- In Visual Studio, right-click the solution.
- Click Add -> Existing Project…
Upgrade the CMSApp_MVC project to MVC 5 if you haven’t upgraded it before.
If you upgraded the CMSApp_MVC project to MVC 5 before upgrading to Kentico 9:
1. Reinstall the Microsoft.AspNet.Mvc package. In the Package Manager Console: Update-Package -Reinstall Microsoft.AspNet.Mvc
2. In the /bin folder of the CMSApp project, delete the CMS.MVC<version>.Impl.dll library.
3. Update the Kentico MVC library.
In the CMSApp project, add a reference to the CMSApp_MVC project.
In the CMSApp_MVC project, remove references to Kentico assemblies (starting with ‘CMS.’).
Add the references again from the CMSApp project’s /Lib folder. Reference the following assemblies: CMS.Base, CMS.Core, CMS.DataEngine, CMS.DocumentEngine, CMS.FileSystemStorage, CMS.Helpers, CMS.Localization, CMS.PortalEngine, and CMS.SiteProvider.
If you plan on using Microsoft ASP.NET Web API after the upgrade, you also need to install the Microsoft ASP.NET Web API NuGet package in the CMSApp_MVC project for the version of Web API that you want to use.
If you do not plan on using Microsoft ASP.NET Web API, perform the following in the CMSApp_MVC project:
- Delete the WebApiConfig.cs file.
- Remove the following lines from the CMS_MvcModule.cs file:
  - using System.Web.Http
  - WebApiConfig.Register(GlobalConfiguration.Configuration);
Build the solution. Do not use the rebuild option.

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 objects and try to import the upgrade_82_90.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 Kentico version 9 licenses for the domains used by your sites:

In the Kentico administration interface, open the Licenses application.
Delete the old version 8 licenses.
Click New license to add your licenses for version 9.

Removed page data columns

In Kentico 9, the database view used when querying page data no longer contains the following columns:

SiteName
NodeOwnerFullName
NodeOwnerUserName
NodeOwnerEmail
Published

You will encounter errors on your site if you use these columns when working with page data. We recommend searching your site for the following:

Instances of web parts that load page data. Check for the columns in SQL properties (WHERE condition, ORDER BY and Columns).
Transformations containing the columns in their code
Any custom SQL queries that work with page data.

You need to remove or replace all occurrences of the given columns:

To replace the SiteName column, prepare modified queries or conditions based on the NodeSiteID column.
- In ASCX transformations, you can use the ObjectTransformation control to get other values based on the NodeSiteID. For example:
```
  <cms:ObjectTransformation 
      runat="server" 
      ObjectType="cms.site" 
      ObjectID='<%# Eval<int>("NodeSiteID") %>' 
      Transformation="{% SiteName %}"
  />


  
```
To replace the NodeOwnerFullName, NodeOwnerUserName or NodeOwnerEmail columns, use the NodeOwner column (stores the ID of the given user).

To replace conditions such as Published = 1, use SQL code similar to the following:




  [DocumentCanBePublished] = 1
  AND
  ([DocumentPublishFrom] IS NULL OR [DocumentPublishFrom] <= GETDATE()) 
  AND
  ([DocumentPublishTo] IS NULL OR [DocumentPublishTo] >= GETDATE())

Abandoned web parts and widgets

Kentico 9 no longer supports several web parts and widgets that were present in previous versions of Kentico (for example the Document library and Drop-down menu). The upgrade procedure deleted their code files but kept their object definitions are in the database. Follow the instructions in Recovering abandoned features, web parts and widgets and either recover the abandoned web parts and widgets or delete them from the system.

Replacing language selectors built with Kentico web parts

Kentico 9 abandons the Language selection, Language selection drop-down, and Language selection with flags web parts. We recommend building language selectors using the new Language data source web part. You can also recover the abandoned web parts.

Project management

Project management features are no longer supported in Kentico 9. Decide whether you wish to continue using project management after you perform the upgrade procedure. See Recovering abandoned features, web parts and widgets for detailed instructions.

Macros

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

Log in to the Kentico administration interface as a global administrator.
Open the System application.
Select the Macros -> Signatures tab.
Enable the Sign all macros option.
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:

In the System application, select the Macros -> Report tab.
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 enable web farms after you complete the upgrade.

We recommend that you enable the web farm on one server or instance and after that you add the remaining servers to the web farm.

In the Kentico administration interface, open the Settings application.
Expand the Versioning & Synchronization -> Web farm category.
Select the Web farm mode:
- Automatic - 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.
Click Save.

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

E-commerce

If your Kentico 8.2 instance contained orders imported from Kentico 7 or older that weren’t recalculated before the upgrade to Kentico 9, taxes will be displayed with values of zero for every order item in invoices and email notifications. However, the final prices is be calculated correctly with taxes.

If you want to prevent this behavior, which can be unpleasant for unfinished orders, run the following code to assign current taxes to all unfinished orders (or all orders if preferred). For example, you can create a user control to run the code.




  // Gets orders for recalculation, for example 1-month-old with a specific order status (orderStatusId) and from a specific site (siteId)
  var orders = OrderInfoProvider.GetOrders(siteId)
                                .WhereGreaterOrEquals("OrderDate", DateTime.Now.AddMonths(-1))
                                .WhereEquals("OrderStatusID", orderStatusId)
                                .Column("OrderID")
                                .GetListResult<int>();

  // Loops through the found orders
  foreach(var orderId in orders)
  {
      // Gets the shopping cart from the order and recalculates it with current taxes, discounts, etc.
      var cart = ShoppingCartInfoProvider.GetShoppingCartInfoFromOrder(orderId);
      cart.InvalidateCalculations();
      ShoppingCartInfoProvider.EvaluateShoppingCart(cart);

      // Saves the recalculated shopping cart as an order without generating an invoice
      bool generateInvoice = false;
      ShoppingCartInfoProvider.SetOrder(cart, generateInvoice);
  }

Since Kentico 7 does not keep the tax values of every order item, you cannot restore the tax values from the time of order creation.

The Registration conversion name and Registration conversion value e-commerce settings that affect the obsolete Checkout process web part were hidden.

If you use the obsolete Checkout process web part and want to display the related settings, run the following SQL script against your Kentico database:




  DECLARE @SiteID INT = YOUR_SITE_ID;
  UPDATE dbo.CMS_SettingsKey
  SET KeyIsHidden = 0
  WHERE KeyName IN ('CMSStoreAllowAnonymousCustomers', 'CMSStoreUseExtraCompanyAddress', 'CMSStoreRequireCompanyInfo', 'CMSStoreShowOrganizationID', 'CMSStoreShowTaxRegistrationID', 'CMSStoreRegistrationConversionName', 'CMSStoreRegistrationConversionValue') AND (SiteID = @SiteID OR SiteID IS NULL)
  UPDATE dbo.CMS_UIElement
  SET ElementVisibilityCondition = NULL
  WHERE ElementName = 'Configuration.Settings.CheckoutProcess' OR ElementName = 'Tools.Ecommerce.CheckoutSettings'

If you want to log conversions in the currently recommended checkout process web parts (composed from multiple web parts), set the conversion properties directly while editing the Registration form web part.

Automatic contact deletion

The automatic contact deletion settings have changed. If you use automatic contact deletion, consider changing the settings to reflect your current requirements.

By default, Kentico 9 uses security tokens to protect pages against Cross site request forgery attacks. If your website uses the cookie law consent features to disable cookies of the Essential level, you will encounter CSRF errors for all POST requests (because the cookie storing security tokens is not available).

If you wish to continue using the restricted cookie level, you need to disable the CSRF security tokens by adding the following key to the appSettings section of your web.config file:




<add key="CMSEnableCsrfProtection" value="false" />

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:

Obtain the new version of the source code solution.
Install the upgrade procedure.
Perform any relevant steps before the upgrade.
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.
Apply the database upgrade.
Open the upgrade installation directory (C:\Program Files\Kentico\9.0\Upgrade82_90 by default), and copy the CMS\CMS\CMSSiteUtils\Import\Upgrade_82_90.zip file into the CMS\CMSSiteUtils\Import folder of the new Kentico 9 project.
Perform all relevant steps after the upgrade.

Prerequisites

Upgrading across multiple versions

Upgrade overview

Class fields

Default objects

Content management

E-commerce

On-line marketing

Installing the upgrade procedure

Steps before you start the upgrade

Custom code analysis

Database schema when using a database connection with Windows authentication

Deployment mode and Source control

Staging, integration and export tasks

Object version history and recycled objects

Macro security

Large database tables and timeouts

E-commerce

Full-text search for Kentico database tables

Large on-line marketing databases

Removing the MVC_App project

Page attachment history

Applying the upgrade

Upgrading separated on-line marketing databases

Steps after performing the upgrade

API changes

Kentico 9 setup files

Customizing the mimetypes.txt file

URL routes with custom extensions

Projects with a Classic application pool

Using the CMSApp_MVC project after the upgrade

Clearing session state data

Running the website - First request

Licenses

Removed page data columns

Abandoned web parts and widgets

Replacing language selectors built with Kentico web parts

Project management

Macros

Web farms

UI personalization

E-commerce

Automatic contact deletion

CSRF errors when using cookie restrictions

Upgrading source code instances