--- title: Upgrading to Kentico 8.2 related: - https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2/upgrading-custom-code.md - https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2/upgrading-projects-under-source-control.md - https://docs.kentico.com/k82/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.1 to 8.2. 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/k82/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. > **Info:** **Microsoft Azure 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/k82/installation/upgrading-to-kentico-8-2/upgrading-microsoft-azure-projects.md) page. ## Prerequisites Before you start the upgrade, please make sure that your environment fulfills the requirements of Kentico 8.2. See [Server and hosting requirements](https://docs.kentico.com/k82/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.1, 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. > **Note:** This does not include all Kentico 8.2 features and changes – see [Release notes - Kentico 8 versions](https://docs.kentico.com/k82/release-notes-kentico-8-versions.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 8.2 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 8.2 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/k82/configuring-kentico/optimizing-website-performance/setting-up-web-farms.md) functionality. You can re-enable web farms 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 8 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/k82/custom-development/developing-form-controls.md) objects are overwritten (both the source files and form control objects in the system). #### E-commerce - **Global shipping options** are replaced with **site** [shipping options](https://docs.kentico.com/k82/e-commerce-features/configuring-and-managing-your-store/configuring-shipping-options.md). - Existing global shipping options are transformed to site shipping options and copied to every site. - Options are transformed completely except for: - Teaser images of the shipping options – if you don't have access to the teaser image files, download them from the system before the upgrade. - Values of custom fields of shipping options – if you created custom fields in the **Ecommerce.ShippingOption** class, you need to set their values manually in the new site shipping options. - If the site [main currency](https://docs.kentico.com/k82/e-commerce-features/configuring-and-managing-your-store/currencies.md) is different from the global main currency, shipping charges and costs are converted to the site default currency according to the site [exchange rate table](https://docs.kentico.com/k82/e-commerce-features/configuring-and-managing-your-store/exchange-rates.md). - Since global shipping options are not supported anymore, you cannot configure shipping in the **Multistore configuration** application. #### Email marketing - The **Newsletters** application (and module) is renamed to **Email marketing**. #### SharePoint integration - The upgrade adds a new **SharePoint** application, which allows [management of SharePoint libraries](https://docs.kentico.com/k82/integrating-3rd-party-systems/integrating-sharepoint/managing-sharepoint-libraries.md). - The original **SharePoint** application is renamed to **SharePoint connections**. ## Installing the upgrade procedure 1. Download the [Kentico 8.2 upgrade](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_8_1_8_2.exe). 2. Run **Upgrade\_8\_1\_8\_2.exe**. 3. Install the upgrade procedure (the installer places the upgrade into the _C:\Program Files\Kentico\8.2\Upgrade81\_82_ folder by default). ## Steps before you start the upgrade ### Custom code analysis > **Info:** For a list of breaking changes in the Kentico 8.2 API, see the [Release notes](https://docs.kentico.com/k82/release-notes-kentico-8-versions.md#releasenoteskentico8versions-breaking). If your project contains any custom code (including virtual objects such as [transformations](https://docs.kentico.com/k82/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-8-2) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/k82/installation/upgrading-to-kentico-8-2/upgrading-custom-code.md) to learn more. The tool has the following functionality: - Detects custom code that is no longer valid in version 8.2 - Provides recommendations for each occurrence of invalid code - Can automatically convert the majority of code to the Kentico 8.2 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/k82/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/k82/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/k82/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/k82/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/k82/configuring-kentico/working-with-object-versioning/objects-recycle-bin.md) - Previous [versions of objects](https://docs.kentico.com/k82/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. ### 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. ## Applying the upgrade We strongly recommend using the [Kentico Upgrade Utility](https://docs.kentico.com/k82/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/k82/installation/upgrading-to-kentico-8-2/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.1 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, 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/k82/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 8.2 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 8.2, 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 8.2 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 8.2 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/k82/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\8.2\Upgrade81\_82_ 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 8.2, including: - Custom or customized code files in the web project - Virtual objects in Kentico, such as [transformations](https://docs.kentico.com/k82/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) and [page layouts](https://docs.kentico.com/k82/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/k82/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-8-2). ### Kentico 8.2 setup files The upgrade converts your web projects to version 8.2, 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/k82/external-utilities.md), sample files, and allow you to install new Kentico 8.2 web projects. To obtain the installer and setup files for Kentico 8.2: 1. Download the [Kentico 8.2 installer](http://download.kentico.com/Kentico_8_2.exe). 2. Run **Kentico\_8\_2.exe**. 3. Read and accept the License Terms and Conditions and click **Custom installation**. 4. Select **Install only program files** and click **Install**. ### Merging web.config probing elements The 8.2 upgrade adds a new element to the project's web.config file. The new element specifies the 'CMSDependencies\Newtonsoft.Json.4.5.0.0' base subdirectory. If you use your own element, you need to merge the 'privatePath' values into a single element. 1. Open the project's web.config file. 2. Merge the value of the new element with the existing one. ```xml ``` 3. Save the web.config file. ### Using Newtonsoft.Json with Kentico Kentico no longer contains the _Newtonsoft.Json_ library in the _Lib_ folder. If you have any custom code that requires the library, install the [_Newtonsoft.Json_ NuGet](https://www.nuget.org/packages/Newtonsoft.Json/) package into the given projects as a replacement. ### Using ASP.NET Web API with Kentico You should now use the [_Microsoft.AspNet.WebApi_ Nuget](https://www.nuget.org/packages/Microsoft.AspNet.WebApi/) package in projects where you use Web API. See [Using ASP.NET Web API with Kentico](https://docs.kentico.com/k82/developing-websites/using-asp-net-web-api-with-kentico.md) for more information. ### 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\_81\_82.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. ### 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/k82/macro-expressions.md) chapter. ### Web farms The upgrade procedure automatically disables web farm functionality. If your Kentico instance runs on a web farm, you need to manually enable web farms after you complete the upgrade. 1. In the Kentico administration interface, open the **Settings** application. 2. Expand the **Versioning & Synchronization -> Web farm** category. 3. Check the **Enable web farm** setting. 4. Click **Save**. ### Marketing automation The 'Property name' value in the 'Set contact property' action displays unnecessary values. To hide the columns: 1. Open the **Marketing automation** application. 2. Switch to **Actions**. 3. Edit the **Set contact property** action. 4. Switch to **Parameters**. 5. Under **Editing control settings**, disable **Show all columns**.