Upgrading to Kentico 9 | Kentico Xperience 9 Documentation

This content cannot be displayed without JavaScript.
Please enable JavaScript and reload the page.

Is this really the version you are looking for? Kentico Xperience 9 Documentation is no longer updated. Use the switcher in the header to choose your product version.

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 className="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>
##paymentreceivedtext##	{$ OrderPaymentNotificationToCustomer.PaymentReceived $}
##thankyoutext##	{$ 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.

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.

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

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:

HTML

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

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):
XML
```
<validation validateIntegratedModeConfiguration="false" />
```

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:
  XML
```
<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:

SQL

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

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'

Cookie consent

Prerequisites

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