--- title: Upgrading to Kentico 9 related: - https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/upgrading-custom-code.md - https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/recovering-abandoned-features-web-parts-and-widgets.md - https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/upgrading-projects-under-source-control.md - https://docs.kentico.com/k9/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 8.2 to 9. > **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/k9/installation/upgrading-to-kentico-9/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/k9/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 9. See [Server and hosting requirements](https://docs.kentico.com/k9/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 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. > **Note:** This does not include all Kentico 9 features and changes – see [Release notes - Kentico 9](https://docs.kentico.com/k9/release-notes-kentico-9.md) 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](http://devnet.kentico.com/download/hotfixes) (you may need to download and install the [latest Kentico 9 upgrade package](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_8_2_9_0.exe)). - 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](https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/recovering-abandoned-features-web-parts-and-widgets.md) 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](https://docs.kentico.com/k9/configuring-kentico/optimizing-website-performance/setting-up-web-farms.md) 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](https://docs.kentico.com/k9/configuring-kentico/managing-sites/configuring-settings-for-sites/settings-versioning-synchronization/settings-web-farm.md) and [Configuring web farm servers](https://docs.kentico.com/k9/configuring-kentico/optimizing-website-performance/setting-up-web-farms/configuring-web-farm-servers.md) 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](https://docs.kentico.com/k9/custom-development/developing-form-controls.md) 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](https://docs.kentico.com/k9/release-notes-kentico-9.md#releasenoteskentico9-breaking) 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](https://docs.kentico.com/k9/e-commerce-features/customizing-and-developing-your-store/product-related-customizing/mapping-product-type-database-columns.md) 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 1. Download the [Kentico 9 upgrade](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_8_2_9_0.exe). 2. Run **Upgrade\_8\_2\_9\_0.exe**. 3. 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 > **Info:** For a list of breaking changes in the Kentico 9 API, see the [Release notes](https://docs.kentico.com/k9/release-notes-kentico-9.md#releasenoteskentico9-breaking). If your project contains any custom code (including virtual objects such as [transformations](https://docs.kentico.com/k9/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-9) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/upgrading-custom-code.md) 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). > **Tip:** 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](https://docs.kentico.com/k9/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/k9/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/k9/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](http://localhost/Kentico82_1124/CMSModules/Settings/Pages/Categories.aspx) -> 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/k9/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/k9/configuring-kentico/working-with-object-versioning/objects-recycle-bin.md) - Previous [versions of objects](https://docs.kentico.com/k9/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/k9/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/k9/on-line-marketing-features/contact-management/working-with-contacts.md) and [activity](https://docs.kentico.com/k9/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/k9/on-line-marketing-features/contact-management/working-with-contacts/setting-up-automatic-deletion-of-contacts.md) 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](https://docs.kentico.com/k9/e-commerce-features/customizing-and-developing-your-store/implementing-custom-shipping-carrier-providers.md) 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## | {$ Ecommerce.Invoice.CompanyAddressTitle $ }{% CompanyAddress.ApplyTransformation("Ecommerce.Transformations.Order\_Address") %} + tweak transformation appearance | | ##TAXREGISTRATIONID## | {% Customer.CustomerTaxRegistrationID %} | | ##ORGANIZATIONID## | {% Customer.CustomerOrganizationID %} | | ##applicationurl## | {% Transformation.GetAbsoluteUrl("\~/").TrimEnd("/") %} | | ##NEWORDERLINK## | {$ Ecommerce.OrderNotification.OpenOrder $} | | ##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](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/checkout-process/displaying-the-shopping-cart-preview-on-pages.md). - The upgrade removes the obsolete **Product filter** web part. To replace the web part, see [Configuring product listings with filtering](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/configuring-product-pages/configuring-product-listings-with-filtering.md). - The upgrade removes the **E-commerce settings checker** widget. Remove the widget from user dashboards in the [Store overview](https://docs.kentico.com/k9/e-commerce-features/managing-your-store/store-reports/store-overview.md)application 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](https://docs.kentico.com/k9/references/reference-web-config-application-keys.md#connection-string). ### 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](https://docs.kentico.com/k9/developing-websites/developing-sites-using-asp-net-mvc.md). ### Page attachment history Kentico 9 allows [storing of page attachment history](https://docs.kentico.com/k9/configuring-kentico/managing-files/storing-files.md) 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: ```xml   ``` ## Applying the upgrade We strongly recommend using the [Kentico Upgrade Utility](https://docs.kentico.com/k9/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/k9/installation/upgrading-to-kentico-9/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 8.2 web project folder (you can select a folder using the **Browse** button). 4. Use the utility to back up your project files and/or database if you haven’t done so already. 5. Select whether you want to upgrade files, 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/k9/on-line-marketing-features/contact-management/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 9 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 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. 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 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). 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/k9/on-line-marketing-features/contact-management/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\9.0\Upgrade82\_90_ 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. > **Note:** **Workaround for separated databases without marketing emails** > > If your separated on-line marketing database does not contain any marketing emails (under [email campaigns](https://docs.kentico.com/k9/on-line-marketing-features/email-marketing/working-with-email-campaigns.md)), 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: > > 1. Open the upgraded project in Visual Studio. > 2. Expand the **App\_Code** (for web site projects) or **Old\_App\_Code** folder (for web application projects), and edit the **CMS\UpgradeProcedure.cs** file. > 3. Comment out the following code that executes queries related to marketing emails (line 1136 by default): > > ```csharp > > // 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); > }*/ > > ``` > 4. Save the changes. > 5. 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. > **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 9, including: - Custom or customized code files in the web project - Virtual objects in Kentico, such as [transformations](https://docs.kentico.com/k9/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) and [page layouts](https://docs.kentico.com/k9/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/k9/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-9). ### 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](https://docs.kentico.com/k9/external-utilities.md), sample files, and allow you to install new Kentico 9 web projects. To obtain the installer and setup files for Kentico 9: 1. Download the [Kentico 9 installer](http://download.kentico.com/Kentico_9_0.exe). 2. Run **Kentico\_9\_0.exe**. 3. Read and accept the License Terms and Conditions and click **Custom installation**. 4. 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](https://msdn.microsoft.com/en-us/library/system.web.routing.urlroutingmodule%28v=vs.100%29.aspx) 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: 1. Edit your application's **web.config** file. 2. Find the **** element inside the **system.webServer** section directly under the web.config root (i.e. not under a specific __ element). 3. Set the **runAllManagedModulesForAllRequests** attribute to _true_ for the opening __ tag: ```html ... ... ``` ### Projects with a Classic application pool Kentico 9 no longer supports _Application Pool_s 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: 1. Run **Internet Information Services (IIS) Manager** in Windows. 2. Select the **Application Pool** used by your application and click **Basic settings**. 3. Switch the **Managed pipeline mode** to _Integrated_ and click **OK**. 4. Edit your project's **web.config** file. 5. Add the following **** element inside the **system.webServer** section directly under the web.config root (i.e. not under a specific __ element): ```xml ``` 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: 1. Add the CMSApp\_MVC project into the solution. - In Visual Studio, right-click the solution. - Click Add -> Existing Project... 2. [Upgrade](https://docs.kentico.com/display/K82/Upgrading+the+MVC+version) the _CMSApp\_MVC_ project to MVC 5 if you haven't upgraded it before. 3. 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.Impl.dll_ library. 3. [Update](https://docs.kentico.com/display/K82/Upgrading+the+MVC+version#UpgradingtheMVCversion-UpdatingtheKenticoMVClibrary) the Kentico MVC library. 4. In the _CMSApp_ project, add a reference to the _CMSApp\_MVC_ project. 5. In the _CMSApp\_MVC_ project, remove references to Kentico assemblies (starting with 'CMS.'). 6. 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._ 7. If you plan on using [Microsoft ASP.NET Web API](https://docs.kentico.com/k9/developing-websites/using-asp-net-web-api-with-kentico.md) 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. 8. 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);_ 9. 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](http://devnet.kentico.com/support) and provide the details of the errors. ### Licenses You need to add Kentico version 9 licenses for the domains used by your sites: 1. In the Kentico administration interface, open the **Licenses** application. 2. Delete the old version 8 licenses. 3. 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](https://docs.kentico.com/k9/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) 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: ```xml ``` - 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()) ``` ### 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](https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/recovering-abandoned-features-web-parts-and-widgets.md) 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](https://docs.kentico.com/k9/multilingual-websites/setting-up-multilingual-websites/configuring-urls-for-multilingual-websites/creating-language-selectors.md) web part. You can also [recover the abandoned web parts](https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/recovering-abandoned-features-web-parts-and-widgets.md). ### Project management [Project management](https://docs.kentico.com/display/K82/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](https://docs.kentico.com/k9/installation/upgrading-to-kentico-9/recovering-abandoned-features-web-parts-and-widgets.md#project-management) for detailed instructions. ### 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/k9/macro-expressions.md) chapter. ### Web farms The upgrade procedure automatically disables [web farm](https://docs.kentico.com/k9/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/k9/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/k9/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.). ### 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](https://docs.kentico.com/k9/custom-development/miscellaneous-custom-development-tasks/adding-custom-code-to-portal-engine-page-templates.md) to run the code. ```csharp // 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(); // 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](https://docs.kentico.com/k9/configuring-kentico/managing-sites/configuring-settings-for-sites/settings-e-commerce.md) 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: ```csharp 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](https://docs.kentico.com/k9/e-commerce-features/configuring-your-store/checkout-process.md) 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](https://docs.kentico.com/k9/on-line-marketing-features/contact-management/working-with-contacts/setting-up-automatic-deletion-of-contacts.md) have changed. If you use automatic contact deletion, consider changing the settings to reflect your current requirements. ### CSRF errors when using cookie restrictions By default, Kentico 9 uses security tokens to protect pages against [Cross site request forgery](https://docs.kentico.com/k9/securing-websites/developing-secure-websites/cross-site-request-forgery-csrf-xsrf.md) attacks. If your website uses the [cookie law consent features](https://docs.kentico.com/k9/configuring-kentico/adding-cookie-law-consent-to-web-pages.md) 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: ```xml ``` ## 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\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. 7. Perform all relevant [steps after the upgrade](#steps-after-performing-the-upgrade).