--- title: Upgrading to Kentico 10 related: - https://docs.kentico.com/k10/installation/upgrading-to-kentico-10/upgrading-custom-code.md - https://docs.kentico.com/k10/installation/upgrading-to-kentico-10/upgrading-projects-under-source-control.md - https://docs.kentico.com/k10/custom-development/best-practices-for-customization.md --- > Agent instructions: > **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown. > > - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version. > - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt). This page provides instructions for upgrading Kentico projects from version 9 to 10. > **Info:** **Upgrading non-standard projects** > > - If you are upgrading a project hosted on Microsoft Azure, please follow the instructions on the [Upgrading Microsoft Azure projects](https://docs.kentico.com/k10/installation/upgrading-to-kentico-10/upgrading-microsoft-azure-projects.md) page. > - If you are upgrading a source code instance, see [Upgrading source code instances](#upgrading-source-code-instances) for a general outline of the recommended process. 1. [Check the prerequisites and Upgrade overview](#prerequisites) 2. [Install the upgrade procedure](#installing-the-upgrade-procedure) 3. [Perform the required steps before the upgrade](#steps-before-you-start-the-upgrade) 4. [Apply the upgrade to your Kentico project](#applying-the-upgrade) 5. [Perform the required steps after the upgrade](#steps-after-performing-the-upgrade) > **Warning:** **Warning** > > Using the [Export and Import](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites.md) 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 10. See [Server and hosting requirements](https://docs.kentico.com/k10/installation/server-and-hosting-requirements.md) 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 9, 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. > **Note:** This does not include all Kentico 10 features and changes – see [Release notes - Kentico 10](https://docs.kentico.com/k10/release-notes-kentico-10.md) for a comprehensive list. - 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 10 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 10 remain in the file system, with an added _.deleted_ extension. These files are not included in the _CMSApp_ project in web application projects. - For web application projects, the upgrade merges the content of the _CMSApp\_AppCode_ project into the main _CMSApp_ project. The _CMSApp\_AppCode_ project is removed from the solution (if custom files were not added). See [Customizations in the CMSApp\_AppCode project](#customizations-in-the-cmsapp_appcode-project) for more information. - If your Kentico project uses Windows authentication (integrated security) for its database connection, the database upgrade scripts automatically set the _Default schema_ of the database user matching the current Windows account (i.e. the user who runs the upgrade utility) to the schema used by the objects in your Kentico database (_dbo_ by default). - The upgrade disables [web farm](https://docs.kentico.com/k10/configuring-kentico/optimizing-website-performance/setting-up-web-farms.md) and [continuous integration](https://docs.kentico.com/k10/developing-websites/preparing-your-environment-for-team-development/setting-up-continuous-integration.md) functionality. You can re-enable the features 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 9 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](https://docs.kentico.com/k10/custom-development/developing-form-controls.md) objects are overwritten (both the source files and form control objects in the system). #### E-commerce - Buy X Get Y discounts now store their priority based on their order in the discount listing in the **Buy X Get Y discounts** application. - The upgrade automatically changes the priority based on their priority values in Kentico 9. - After the upgrade, you will see the Buy X Get Y discounts ordered based on their previous priority values. - In the database, the priority (and order) is now saved as an integer. - Store managers can no longer manage only specific [departments](https://docs.kentico.com/k10/e-commerce-features/managing-your-store/products/categorizing-products/departments.md). If you used department managers, the managers will have access to all departments after the upgrade. **On-line marketing** - The _Abuse report_, _Accept initiated chat request_, _Accept automatically initiated chat request_, _Chat request support_, _Chat request support using offline form_, _Customer registration_, _Joining a group_, _Leaving a group_ and _User contribution_ activity types are not supported in Kentico 10. - The upgrade automatically converts the activity types to custom. - The system no longer logs activities of these types. - After the upgrade, [personas](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/personas.md), [scoring,](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/scoring-contacts.md) [ account statuses](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts/organizing-contacts-into-accounts.md#assigning-statuses-to-accounts), [contact statuses](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts/assigning-statuses-to-contacts.md), [contact roles](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts/organizing-contacts-into-accounts.md) and [contact groups](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/segmenting-contacts-into-contact-groups.md) are converted from site-specific to global objects. Objects that have the same code name on different sites will obtain a _SiteID_ suffix. The code name change may break existing macro conditions that use the given objects. - The upgrade changes the persona object code name to _PersonaCodeName\_SiteID_. - The upgrade changes the scoring object code name to _ScoreCodeName\_SiteID_. - The upgrade changes the account status object code name to _AccountStatusCodeName\_SiteID_. - The upgrade changes the contact status object code name to _ContactStatusCodeName\_SiteID_. - The upgrade changes the contact role object code name to _ContactRoleCodeName\_SiteID_. - The upgrade changes the contact group object code name to _ContactGroupCodeName\_SiteID_. - After the upgrade, [email templates](https://docs.kentico.com/k10/configuring-kentico/managing-email-templates.md) of the _Automation_ email type are converted from site-specific to global objects. As a result, it is only possible to create a global email template of the _Automation_ email type. The code name of Automation email templates will obtain the _SiteID_ suffix. The code name change may break existing macro conditions that use the given object, and affect the email template based _Send email_ steps in your marketing automation processes. - The upgrade changes the code name of Automation email template to _AutomationEmailTemplateCodeName\_SiteID_. - The upgrade removes the _Opt-out list_ setting for choosing between _Opt-out list is shared between all sites_ and _Opt-out list is separate for each site_ options. If you have previously selected the _Opt-out list is separate for each site_ option, the recipients of your [marketing emails](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing.md) will be unsubscribed from all email campaigns and newsletters on all sites. - The upgrade removes newsletter recipients that were added as personas, roles, subscribers, and users. If you need to retain the existing subscribers, see [On-line marketing - Keeping original subscribers](#upgradingtokentico10-keepingoriginalsubscribers). - The upgrade stops all running [campaigns](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/campaigns.md) and removes reports from all campaigns due to major changes in the campaign architecture. - After the upgrade, the _Contact management_ module can no longer be separated from the Kentico system by removing the _On-line marketing_ module. - The upgrade makes [contacts](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts.md) and static [contact groups](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/segmenting-contacts-into-contact-groups.md) available in the Kentico CMS edition. - The upgrade removes the fields for collecting the _ContactAddress2_, _ContactHomePhone_, _ContactLastLogon_, _ContactSalutation_, _ContactTitleAfter_, _ContactTitleBefore_ and _ContactWebSite_ data. The deletion of the mentioned fields may break existing macro conditions that use the given columns as parameters, affect your marketing automation processes that contain the _Set contact property_ steps with the _Address 2, _Home phone_, _Last logon,_ _Salutation_,_ _Title after_, _Title before_ and _Web URL_ parameters, and break the mapping of the removed contact fields to forms, Salesforce leads, customers, and users. - After the upgrade, it is only possible to [merge contacts automatically](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts/merging-contacts.md). The upgrade removes the bindings between contacts or accounts that were merged before the upgrade. As a result, these contacts and accounts behave as not merged objects. Their activities and memberships are moved to the respective parent contacts or accounts. - The upgrade removes the _OnlineMarketingFunctions_ class from the public API. If you have used the class in your [transformations](https://docs.kentico.com/k10/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md), these transformations will not work after the upgrade. You can replace the removed class by implementing a custom class that uses the functionality of the _ISubscriptionService_, _IUnsubscriptionProvider_ and _ActivityInfoProvider_ classes. ## Installing the upgrade procedure 1. Download the [Kentico 10 upgrade](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_9_0_10_0.exe). 2. Run **Upgrade\_9\_0\_10\_0.exe**. 3. Install the upgrade procedure (the installer places the upgrade into the _C:\Program Files\Kentico\10.0\Upgrade90\_100_ folder by default). ## Steps before you start the upgrade ### Custom code analysis > **Info:** For a list of breaking changes in the Kentico 10 API, see the [Release notes](https://docs.kentico.com/k10/release-notes-kentico-10.md#releasenoteskentico10-breakingapi). If your project contains any custom code (including virtual objects such as [transformations](https://docs.kentico.com/k10/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md)), we strongly recommend using the **Kentico code upgrade tool** before you start the upgrade procedure. Download the tool from the [API Changes](http://devnet.kentico.com/documentation/api-changes/kentico-10) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/k10/installation/upgrading-to-kentico-10/upgrading-custom-code.md) to learn more. The tool has the following functionality: - Detects custom code that is no longer valid in version 10 - Provides recommendations for each occurrence of invalid code - Can automatically convert the majority of code to the Kentico 10 API The code upgrade tool’s output will help you update your custom code after you perform the upgrade. ### Deployment mode and Source control If your system stores virtual objects on the file system (due to enabled [deployment mode or source control](https://docs.kentico.com/k10/deploying-websites/deployment-mode-for-virtual-objects.md) 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](https://docs.kentico.com/k10/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/k10/integrating-3rd-party-systems/using-the-integration-bus.md), 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](https://docs.kentico.com/k10/deploying-websites/exporting-and-importing-sites.md) 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](https://docs.kentico.com/k10/configuring-kentico/working-with-object-versioning/objects-recycle-bin.md) - Previous [versions of objects](https://docs.kentico.com/k10/configuring-kentico/working-with-object-versioning.md) 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. ### 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: 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](https://docs.kentico.com/k10/macro-expressions/troubleshooting-macros/working-with-macro-signatures.md). ### 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](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts.md) and [activity](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/tracking-contact-activities.md) 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](https://docs.kentico.com/k10/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-contacts/setting-up-automatic-deletion-of-contacts.md) 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. ### E-commerce – Invoice attachments Since adding attachments to site invoices is removed in Kentico 10, move your attachments to a different place (for example, to the [media library](https://docs.kentico.com/k10/managing-website-content/working-with-files/media-library-files.md)). ### SalesForce replication scheduled task The _SalesForce replication_ scheduled task is no longer site-specific, but global only. If you have used the customized _SalesForce replication_ scheduled tasks for your sites, back up the settings of customized tasks. - The upgrade deletes all site-specific _SalesForce replication_ scheduled tasks. - The upgrade creates a scheduled task with the default settings, which is global now. ### On-line marketing – Adding the On-line marketing module In case you have not already installed the _On-line marketing_ module, add the module to your Kentico system to ensure that the upgrade process runs correctly. You may uninstall the _On-line marketing_ module after the successful upgrade. ### On-line marketing – Removing the Campaign hits widget Kentico 10 does not contain the _campaign.dayreport.graph_ chart displayed by the **Campaign hits** widget in the **Marketing overview** application anymore. However, the upgrade does not remove the widget, therefore the widget displays an error message. Remove the widget from user dashboards in the **Marketing overview** application or inform your users to remove the widget from their dashboards. ### On-line marketing – Removing the Campaign reports The upgrade removes all Campaign reports. However, if you saved any Campaign reports in the **Reporting** application in the **Web analytics -> Campaign** category, you need to delete the saved reports. ### On-line marketing – Removing the Unsubscription request web part The upgrade removes the obsolete _Unsubscription request_ web part. If you used the web part on your site, you need to remove the web part instances from your pages and page templates. You also need to delete the web part in the **Web parts** application. To allow users to cancel their subscription, use [unsubscription links](https://docs.kentico.com/k10/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/integrating-email-feeds-into-sites.md) in your emails or the _{% UnsubscribeLink|(resolver)subscriber %}_ macro on source pages for [page-based newsletters](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/email-marketing/creating-newsletters.md) . ### On-line marketing – Removing the Update from Data.com action step The upgrade removes the _Update from Data.com_ action step. If you used the action step in your marketing automation processes, you need to remove these action steps from the existing automation processes. The Data.com integration stopped working as of 1st September 2016, because [Data.com](http://data.com/) terminated third party access to their API. ### On-line marketing – Replacing the removed fields by custom fields If you need to keep collecting the data that was previously gathered by the removed _Address 2_, _Home phone_, _Last logon_, _Salutation_, _Title after_, _Title before_ and _Web URL_ fields, you can create custom fields that will collect the data instead. Replace the removed fields with the custom fields in the following: - Marketing automation processes containing the _Set contact property_ steps with the _Address 2_, _Home phone_, _Last logon_, _Salutation_, _Title after_, _Title before_ and _Web URL_ parameters - Mapped _Address 2_, _Home phone_, _Last logon_, _Salutation_, _Title after_, _Title before_ and _Web URL_ contact fields to forms, Salesforce leads, customers, and users - Macro conditions using _ContactAddress2_, _ContactHomePhone_, _ContactLastLogon_, _ContactSalutation_, _ContactTitleAfter_, _ContactTitleBefore_ and _ContactWebSite_ parameters ### On-line marketing – Running the SQL script to keep the Address 2 data If you need to keep the _ContactAddress2_ data that was previously gathered by the removed _Address 2_ field, run the following SQL script against your Kentico database: ```sql UPDATE OM_Contact SET ContactAddress1 = CASE WHEN (ContactAddress1 IS NOT NULL AND ContactAddress1 <> '') THEN CONCAT(ContactAddress1, ', ', ContactAddress2) ELSE ContactAddress2 END WHERE ContactAddress2 IS NOT NULL AND ContactAddress2 <> '' ``` The SQL script merges the _ContactAddress2_ and _ContactAddress1_ data into the _ContactAddress1_ data, which is now being gathered by the _Address_ field. ### On-line marketing – Keeping original subscribers If you need to keep the original subscribers (added either as personas, roles, subscribers, or users), perform the following steps for individual types of subscribers. **Subscribers and users** 1. Get a list of the specific type of subscribers by running the following SQL script against your Kentico database. - For subscribers ```sql SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] IS NULL ``` - For users ```sql SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] = 'cms.user' ``` 2. For each entry in the list: 1. Check that a matching contact exists in the _OM\_Contact_ database table by comparing values in the _ContactEmail_ column to values in the _SubscriberEmail_ column. - Note that the email addresses of the _cms.user_ subscriber type are stored in the _Email_ column of the _CMS\_User_ database table. 2. If a matching contact does not exist, create a new contact that uses values from the _SubscriberEmail, SubscriberFirstName,_ and _SubscriberLastName_ columns. 3. Update the subscriber entry to use _om.contact_ as the _SubscriberType_, and respective contact ID as the _SubscriberRelatedID._ **Personas and roles** 1. Get a list of the subscribers added as personas and roles by running the following SQL script against your Kentico database. ```sql SELECT * FROM [Newsletter_Subscriber] WHERE [SubscriberType] = 'personas.persona' OR [SubscriberType] = 'cms.role' ``` 2. Create condition-based contact groups for roles and personas: 1. Open the **Contact groups** application in Kentico. 2. Create a **New contact group** and enable the **Condition-based contact group** option. 3. Edit the **Macro condition**for the contact group. 4. Use either _Contact is in persona_ or _Contact is in role_ macro rule and select personas or roles based on the subscriber type. 3. Assign the contact groups to a newsletter. ## Applying the upgrade We strongly recommend using the [Kentico Upgrade Utility](https://docs.kentico.com/k10/external-utilities/kentico-hotfix-and-upgrade-utility.md) to perform the upgrade automatically. > **Info:** **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](https://docs.kentico.com/k10/installation/upgrading-to-kentico-10/upgrading-kentico-manually.md). 1. Open the folder where you installed the upgrade. 2. Run the **Kentico Upgrade Utility** (_Upgrade.exe)_. 3. Enter the path to your Kentico 9 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). > **Note:** **Important**: If you use a [separated on-line marketing database](https://docs.kentico.com/k10/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/separating-the-contact-management-database.md), 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](#upgrading-separated-on-line-marketing-databases) below). > **Note:** **Warning**: If you enable the **Overwrite all files** option in _advanced mode_, the upgrade replaces all project files with the default Kentico 10 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 10, 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 10 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 10 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: - 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](https://docs.kentico.com/k10/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/separating-the-contact-management-database.md), you need to manually run the upgrade SQL scripts after updating the project files: 1. Open the upgrade installation directory (_C:\Program Files\Kentico\10.0\Upgrade90\_100_ 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) > **Info:** **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. ## 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. > **Warning:** **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 10, including: - Custom or customized code files in the web project - Virtual objects in Kentico, such as [transformations](https://docs.kentico.com/k10/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) and [page layouts](https://docs.kentico.com/k10/developing-websites/developing-websites-using-the-portal-engine/editing-page-layouts.md) Use the output of the Kentico code upgrade tool (described in [Custom code analysis](#custom-code-analysis)) to find occurrences of invalid code and recommendations on how to fix or replace them. **Tip**: Enable [Deployment mode](https://docs.kentico.com/k10/deploying-websites/deployment-mode-for-virtual-objects.md) 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](http://devnet.kentico.com/documentation/api-changes/kentico-10). > **Note:** **Important** > > Kentico 10 introduces significant changes in the public API. In general, API related to web form presentation logic is separated from the original libraries and moved to new libraries with the _Web.UI_ suffix. > > The following changes affect some of the most commonly used components and API: > > | Old namespace | New namespace | Comment | > | -------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | CMS.Controls | CMS.DocumentEngine.Web.UI | Includes most [Kentico controls](https://docs.kentico.com/k10/references/kentico-controls.md) intended for live website content. | > | CMS.FormControls | CMS.FormEngine.Web.UI | Includes the **FormEngineUserControl** base class for [custom form controls](https://docs.kentico.com/k10/custom-development/developing-form-controls.md). | > | CMS.ExtendedControls | CMS.Base.Web.UI | Includes the **ControlExtender** and **PageExtender** base classes for [UI extenders](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-extenders-for-module-interface-pages.md). | > | CMS.PortalControls | CMS.PortalEngine.Web.UI | Includes **CMSAbstractWebPart** and other [web part base classes](https://docs.kentico.com/k10/custom-development/developing-web-parts/creating-new-web-parts.md). | > > In addition to using the code upgrade tool, we recommend performing _**mass replaces**_ for the namespace names listed above within your upgraded Kentico project and any other custom projects that use the Kentico API. > > For more details and information, see the list of breaking changes in the [Release notes](https://docs.kentico.com/k10/release-notes-kentico-10.md) and the [API Changes page on DevNet](http://devnet.kentico.com/documentation/api-changes/kentico-10). ### Automated tests The upgrade removes the _CMS.Tests_ library from the Kentico project. If you have any automated tests that utilize the library (for base classes etc.), you need to perform the following steps: 1. Open your Kentico solution in Visual Studio. 2. If you use separate testing projects, you need to manually remove any references to the original _CMS.Tests_ library. > **Info:** If you have custom tests directly within the Kentico _CMSApp_ project or the _App\_Code_ folder of web site projects, you do not need to remove references. The upgrade automatically deletes references to removed libraries within the Kentico projects. 3. Install the **Kentico.Libraries.Tests** NuGet package into the projects that contain your tests. The package provides a replacement for the original testing API. 4. Verify that your tests work as expected with the new version of the testing API. ### Customizations in the CMSApp\_AppCode project For web application installations, the upgrade attempts to merge the **CMSApp\_AppCode** project into the main **CMSApp** project. If you customized the _CMSApp\_AppCode_ project, you may need to perform additional steps after the upgrade: - **No customizations** – all files are moved into the _CMSApp_ project and _CMSApp\_AppCode_ is removed from the solution. No manual steps are required apart from rebuilding the _CMSApp_ project (this may be done automatically as part of the upgrade procedure). - **Customized default files** – both customized and unchanged files are moved into the _CMSApp_ project and _CMSApp\_AppCode_ is removed from the solution. We recommend testing the custom functionality after you finish the remaining steps of the upgrade. - **Added custom files** – if you have added custom files into the _CMSApp\_AppCode_ project, it remains in the solution. All default files are moved to the _CMSApp_ project and only the custom files remain. We recommend that you move any classes into a custom _Class Library_ project (assembly), include any other files (web forms, user controls, web services, etc.) into the main _CMSApp_ project, and then remove _CMSApp\_AppCode._ ### Customized device profile files Kentico 10 changes the code name of the _Device profiles_ module from _CMS.DeviceProfile_ to _CMS.DeviceProfiles._ The change affects the names of the related module folders within the project: - CMS\App\_Data\CMSModules\DeviceProfile - CMS\CMSModules\DeviceProfile - CMS\CMSWebParts\DeviceProfile The upgrade performs the following changes: - New folders named **DeviceProfiles** are created in the same general locations, containing the Kentico 10 versions of the related files. - If you have customized or replaced any of the default files (for example the **51degrees.dat** or **devices.xml** files in _CMS\App\_Data\CMSModules\DeviceProfile_), the files remain in the old _DeviceProfile_ folders, with the _.deleted_ extension added. To preserve your customizations, you need to: 1. Move your customized files to the new _DeviceProfiles_ folder. 2. Remove the _.deleted_ extension for each file and merge your customizations with the new content if necessary. 3. Delete all old _DeviceProfile_ folders. ### Custom mime types The _App\_Data/mimetypes.txt_ file used to register custom media types was removed in Kentico 10. If you had any custom media types registered in the _mimetypes.txt_ file, you need to register them by calling _MimeTypeHelper.AddRule(string mimetype, string extension)_ in the **OnInit()** method of a [custom module class](https://docs.kentico.com/k10/custom-development/creating-custom-modules/initializing-modules-to-run-custom-code.md). ```csharp using CMS; using CMS.DataEngine; using CMS.Helpers; ... // Initializes your module. Called when the application starts. protected override void OnInit() { base.OnInit(); // Registers the mime type for a custom module class MimeTypeHelper.AddRule("application/x-doom", ".wad"); } ... ``` ### Custom forum layouts Kentico 10 requires a different approach for creating custom forum layouts in the _CMS\CMSModules\Forums\Controls\Layouts_ folder. If your project contains one or more custom forum layouts, you need to move the layout folders up one level in the file system and modify the **Forum layout selector** form control. See [Customizing forum design](https://docs.kentico.com/k10/community-features/forums/customizing-forum-design.md) for more information. ### Kentico 10 setup files The upgrade converts your web projects to version 10, 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](https://docs.kentico.com/k10/external-utilities.md), sample files, and allow you to install new Kentico 10 web projects. To obtain the installer and setup files for Kentico 10: 1. Download the [Kentico 10 installer](http://download.kentico.com/Kentico_10_0.exe). 2. Run **Kentico\_10\_0.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 (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, 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\_90\_10\_0.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](http://devnet.kentico.com/support) and provide the details of the errors. ### Licenses You need to add Kentico version 10 licenses for the domains used by your sites: 1. In the Kentico administration interface, open the **Licenses** application. 2. Delete the old version 9 licenses. 3. Click **New license** to add your licenses for version 10 ### 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](https://docs.kentico.com/k10/macro-expressions.md) chapter. ### Recursive macros By default, macros in version 10 do not resolve recursively (if the result of a macro contains further macro expressions, they are not resolved). If your website contains any macros that need to be resolved recursively, add the _(recursive)true_ [macro parameter](https://docs.kentico.com/k10/macro-expressions/macro-syntax.md#macro-parameters) to the given expressions. For example, macros that require recursive resolving may be present in email notification templates. ### Password reset email templates Kentico 10 always requires email approval when resetting [forgotten passwords](https://docs.kentico.com/k10/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/forgotten-password.md). After submitting password reset requests, users now receive emails based on the _Membership - Change password request_ email template, and the _Membership - Forgotten password_ template is no longer used. If your website previously used the password reset functionality without email approval and a modified or custom _Membership - Forgotten password_ email template, you need to transfer your custom content to the _Membership - Change password request_ template. Additionally, a new _Send password reset confirmation email_ setting (found under _Settings -> Security & Membership -> Passwords_) was introduced. Enabled by default, this feature sends users an additional email upon a successful password reset. This email is based on the _Membership - Password reset confirmation_ email template. If you want to use this feature and use customized email templates, you need to customize this template accordingly. ### User password change email templates Kentico 10 now uses two different email templates when changing a user's password through the _Users_ application's _Password_ tab, or the _Customers_ application's _Login details_ tab. If you [generate a new password](https://docs.kentico.com/display/K10/User+management#Usermanagement-Password) for a user, the system uses the _Membership - Changed password_ email template. If you [manually change the password](https://docs.kentico.com/display/K10/User+management#Usermanagement-Password) for a user, the system uses a new _Membership - Password reset confirmation_ email template. If your website previously used a custom or modified version of the _Membership - Changed password_ email template and you use the change password functionality, you need to transfer your customization to the _Membership - Password reset confirmation_ email template . ### On-line marketing macros After the upgrade, the _Contact has opened specified email campaign in the last X days_, _Contact has visited the specified page in the last X days_, _Contact has voted in the specified poll_, _Contact is in community group_, _Contact is in role_ and _Contact is subscribed to a specified email campaign_ macro rules no longer use code name parameters, but GUIDs. The change of code name parameter to GUID will break your existing macro conditions that use these macro rules. The values in the affected macro rules need to be selected again and re-saved. The upgrade also updates the code of the following macro rules: - Activity 'External search' performed for keyword - Activity 'Internal search' performed for keyword The upgrade also changes the display names of the following macro rules: - The _Contact has opened specified email campaign in the last X days_ macro rule is renamed to _Contact has opened the specified email feed in the last X days._ - The _Contact is subscribed to a specified email campaign_ macro rule is renamed to _Contact is subscribed to the specified newsletter._ If you use these macro rules in the conditions of [automation process triggers](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation/setting-triggers-for-automation-processes.md), you need to re-save the conditions. ### Scoring and persona rules Due to performance optimizations, Kentico 10 removes several fields from the configuration of [scoring](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/scoring-contacts/managing-contact-scores.md) or [persona rules](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/personas/defining-personas.md) based on certain types of activities. - **Page visit** and **Landing page** activities no longer provide the **Query string** field in the activity details. - **Internal search** and **External search** activities no longer provide the following fields: - **Search provider** – can be replaced by adding conditions for the _URL referrer_ field. - **Search key word** – can be replaced by changing the _Rule type_ to _Macro_ and using the _Contact has searched for specified keywords_ macro rule in the condition. If your website used rules with conditions for the removed fields, you need to evaluate whether the rules are still relevant. Either delete the rules or update their activity details as required. ### Web farms The upgrade procedure automatically disables [web farm](https://docs.kentico.com/k10/configuring-kentico/optimizing-website-performance/setting-up-web-farms.md) 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. 1. In the Kentico administration interface, open the **Settings** application. 2. Expand the **Versioning & Synchronization -> Web farm** category. 3. 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](https://docs.kentico.com/k10/configuring-kentico/optimizing-website-performance/setting-up-web-farms/configuring-web-farm-servers.md). 4. Click **Save**. ### UI personalization If you have [UI personalization](https://docs.kentico.com/k10/managing-users/ui-personalization.md) 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.). ### Customized extender files Kentico 10 moves many of the default [extender classes](https://docs.kentico.com/k10/custom-development/creating-custom-modules/creating-extenders-for-module-interface-pages.md) from public files in the Kentico project's _App\_Code_ (or _Old\_App\_Code)_ folder into compiled libraries. Extenders adjust the behavior or content of specific pages in the Kentico administration interface. If you have modified one of the default extender files that was moved to a library, your customizations will no longer apply to the administration interface. In such cases, the modified extender file remains in the original location, but the related UI element uses the default extender from the library instead. To re-apply your extender customizations after the upgrade, choose one of the following solutions: - Find the [UI element](https://docs.kentico.com/k10/custom-development/creating-custom-modules/reference-managing-ui-elements.md) that originally used the extender in the **Modules** application. _Customize_ the element and assign your modified extender class on the **Properties** tab. > **Note:** Customizing the default UI elements is not recommended in general, but may be the easiest option in this scenario. > > **Note**: The system may overwrite your UI element customizations when upgrading or hotfixing to a newer versions. We recommend maintaining a list of any UI elements that you customize, so you can check if your extender settings were overwritten and assign them again if necessary. – OR – - Create a [custom module](https://docs.kentico.com/k10/custom-development/creating-custom-modules.md) in the **Modules** application and add UI elements that copy the settings of the original UI elements. Then assign your custom extenders on the **Properties** tab and use the resulting interface instead of the original. ### E-commerce – Shipping options and payment methods The upgrade procedure removes binding of shipping options and payment methods. If you used this feature, you can customize Kentico to achieve the same result. See [Making payment methods dependent on shipping options](https://docs.kentico.com/k10/e-commerce-features/customizing-and-developing-your-store/payment-related-customizing/making-payment-methods-dependent-on-shipping-options.md). ### E-commerce – The EcommerceTransformationFunctions class moved The _EcommerceTransformationFunctions_ class was moved to the _CMS._Ecommerce_.Web.UI_ library/namespace. If your website uses ASCX transformations that call methods from this class, you need to update the namespace in the transformation code. This also applies to the default samples sites upgraded to Kentico 10. ### On-line marketing – Configuring marketing automation steps The upgrade changes [contacts](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts.md) to global objects. As a result, you need to manually set the _site_ and _email feed_ parameters in the _Send campaign email_ step properties and the _site_ and _newsletter_ parameters in the _Newsletter subscription_ step properties of all your marketing automation processes that you intend to use. You also need to manually set the _site_ parameter in the _Log custom activity_ step properties of all your processes that you intend to use. - The upgrade also renames the _Send campaign email_ action step to _Send marketing email_. ### On-line marketing – Localized email campaign and newsletter display names Email campaigns and newsletters in Kentico no longer provide a localizable display name (using macros). If you used email campaigns or newsletters with a localization resource string, the display name will no longer be evaluated. Change the email campaign's or newsletter's display name so that it is displayed as required. ### On-line marketing – Rebuilding contact groups and recalculating scoring and persona rules If you used the removed _ContactAddress2_, _ContactHomePhone_, _ContactLastLogon_, _ContactSalutation_, _ContactTitleAfter_, _ContactTitleBefore_ and _ContactWebSite_ columns as parameters in your macro conditions, it is possible that your condition-based contact groups, scoring and persona rules are not up-to-date. Therefore, we recommend that you rebuild your condition-based [contact groups](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/segmenting-contacts-into-contact-groups.md#setting-up-condition-based-contact-groups), and recalculate your [scoring](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/scoring-contacts/managing-contact-scores.md#recalculating-scores) and [persona rules](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/personas/defining-personas.md#defining-persona-rules). ### On-line marketing – Relative activity URLs In Kentico 10, activity URLs can only be absolute. If you used any [scoring](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/scoring-contacts.md) or [persona](https://docs.kentico.com/k10/on-line-marketing-features/managing-your-on-line-marketing-features/personas.md) condition rules with a relative activity URL, change the URL to absolute and resave the rule. ### On-line marketing – Roles with on-line marketing permissions As the permission model of the _Contact management_ module was changed in Kentico 10, the upgrade removes these permissions from all roles. If you used these permissions, assign them again based on the new model. See [Configuring on-line marketing permissions](https://docs.kentico.com/k10/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-on-line-marketing-permissions.md) for more information. ### On-line marketing – Salesforce integration performance The upgrade modifies database indexes related to on-line marketing in order to optimize performance for the most typical scenarios. The index changes may have a negative effect if you actively use the [Saleforce integration](https://docs.kentico.com/k10/integrating-3rd-party-systems/salesforce-integration.md) to replicate Kentico contacts into Salesforce leads (with a large number of contacts in the database). In these cases, we recommend manually creating a **database index** with the following columns on the **OM\_Contact** database table: 1. ContactSalesForceLeadID 2. ContactSalesForceLeadReplicationDisabled 3. ContactSalesForceLeadReplicationSuspensionDateTime The index should be non-clustered and non-unique. See the [Create Nonclustered Indexes](https://msdn.microsoft.com/en-us/library/ms189280.aspx) article for more information. ### Localized form display names Forms in Kentico no longer provide a localizable display name (using macros). If you used forms with a localization resource string, the display name will no longer be evaluated. Change the form's display name so that it is displayed as required. ### Compilation performance Newly installed Kentico 10 projects contain CodeDOM providers that use the [.NET Compiler Platform ("Roslyn")](https://github.com/dotnet/roslyn) compiler. This improves the compilation performance of the project and significantly speeds up the first load time of the website. To avoid potential conflicts, the upgrade procedure does not automatically add the CodeDOM providers into existing projects. However, we recommend installing the providers manually after you perform the upgrade: 1. Open your Kentico solution in Visual Studio. 2. Right-click the main web project in the Solution Explorer and select **Manage NuGet Packages**. 3. Install the [Microsoft.CodeDom.Providers.DotNetCompilerPlatform](https://www.nuget.org/packages/Microsoft.CodeDom.Providers.DotNetCompilerPlatform/) NuGet package (version 1.0.1 or newer). > **Note:** **Note**: Installed NuGet packages are not maintained by Kentico in any way and you can upgrade them to newer versions as required. This also applies to fresh installations of Kentico. ## 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: 1. Obtain the new version of the source code solution. 2. [Install the upgrade procedure](#installing-the-upgrade-procedure). 3. Perform any relevant [steps before the upgrade](#steps-before-you-start-the-upgrade). 4. 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. 5. [Apply](#applying-the-upgrade) the database upgrade. 6. Open the upgrade installation directory (_C:\Program Files\Kentico\10.0\Upgrade90\_100_ by default), and copy the **CMS\CMS\CMSSiteUtils\Import\Upgrade\_90\_100.zip** file into the **CMS\CMSSiteUtils\Import** folder of the new Kentico 10 project. 7. Perform all relevant [steps after the upgrade](#steps-after-performing-the-upgrade).