---
title: Upgrading to Kentico 8.1
related:
  - https://docs.kentico.com/k81/installation/upgrading-to-kentico-8-1/upgrading-custom-code.md
  - https://docs.kentico.com/k81/installation/upgrading-to-kentico-8-1/upgrading-projects-under-source-control.md
  - https://docs.kentico.com/k81/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 to 8.1.

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/k81/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/k81/installation/upgrading-to-kentico-8-1/upgrading-microsoft-azure-projects.md) page.

## Prerequisites

Before you start the upgrade, please make sure that your environment fulfills the requirements of Kentico 8.1. See [Server and hosting requirements](https://docs.kentico.com/k81/installation/server-and-hosting-requirements.md) for details.

You can upgrade from any type of Kentico 8 project, including all hotfix versions.

**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.0, 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.1 features and changes — see [Release notes - Kentico 8.1](https://docs.kentico.com/k81/release-notes-kentico-8-1.md) for a comprehensive list.

- Kentico 8.1 updates the document terminology — the word _Document_ is replaced by **Page** in the administration interface. This affects the names of applications, web parts, and other related text. Code names and API keywords remain unchanged.
- 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.1 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.1 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/k81/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/k81/custom-development/developing-form-controls.md) objects are overwritten (both the source files and form control objects in the system).

#### E-commerce

- The **Shopping cart contains product** order rule for order discount and free shipping offer conditions is now obsolete.

  - Existing discounts keep the rule and continue to work after the upgrade, but the rule is disabled for new discounts.
  - For new rules, you can use the new **Shopping cart contains products** order rule with options _All_ and _Any_.
  - To allow the obsolete rule for new discounts, go to **Store configuration -> Discount rules -> Order rules**, edit the rule and enable it.
- The **Bundle items selector** [form control](https://docs.kentico.com/k81/custom-development/developing-form-controls.md) is now obsolete.

  - To create fields for selecting which products belong to a bundle, use the **Multiple object binding control** form control and set the **Binding object type** to _ecommerce.bundle_.

#### LinkedIn integration

- The **LinkedIn apply with** web part was removed (LinkedIn no longer supports this functionality).

## Installing the upgrade procedure

1. Download the [Kentico 8.1 upgrade](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_8_0_8_1.exe).
2. Run **Upgrade\_8\_0\_8\_1.exe**.
3. Install the upgrade procedure (the installer places the upgrade into the _C:\Program Files\Kentico\8.1\Upgrade80\_81_ folder by default).

## Steps before you start the upgrade

### Custom code analysis

> **Info:** For a list of breaking changes in the Kentico 8.1 API, see the [Release notes](https://docs.kentico.com/k81/release-notes-kentico-8-1.md#releasenoteskentico8.1-breaking).

If your project contains any custom code (including virtual objects such as [transformations](https://docs.kentico.com/k81/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-1) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/k81/installation/upgrading-to-kentico-8-1/upgrading-custom-code.md) to learn more.

The tool has the following functionality:

- Detects custom code that is no longer valid in version 8.1
- Provides recommendations for each occurrence of invalid code
- Can automatically convert the majority of code to the Kentico 8.1 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/k81/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.

### Separated on-line marketing database

The upgrade is NOT supported for instances with a separated on-line marketing database. In this case, you need to rejoin the database before starting the upgrade procedure. You can perform the separation again after the upgrade is complete.

See also: [Separating the contact management database](https://docs.kentico.com/k81/on-line-marketing-features/contact-management/separating-the-contact-management-database.md)

### Staging, integration and export tasks

If your project uses [staging](https://docs.kentico.com/k81/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/k81/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 Kentico 8 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/k81/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/k81/configuring-kentico/working-with-object-versioning/objects-recycle-bin.md)
- Previous [versions of objects](https://docs.kentico.com/k81/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/k81/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/k81/installation/upgrading-to-kentico-8-1/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 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:** **Warning**: If you enable the **Overwrite all files** option in _advanced mode_, the upgrade replaces all project files with the default Kentico 8.1 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.1, 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 does not 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.1 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.1 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.

## 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.1, including:

- Custom or customized code files in the web project
- Virtual objects in Kentico, such as [transformations](https://docs.kentico.com/k81/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) and [page layouts](https://docs.kentico.com/k81/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/k81/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-1).

### Kentico 8.1 setup files

The upgrade converts your web projects to version 8.1, 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/k81/external-utilities.md), sample files, and allow you to install new Kentico 8.1 web projects.

> **Note:** **Note**: If you do not install the 8.1 version of the setup files, you may encounter incorrect behavior when using the [Kentico Installation Manager](https://docs.kentico.com/k81/external-utilities/kentico-installation-manager.md) utility. The original 8.0 version of the utility cannot correctly identify Kentico 8.1 projects and handles them as 8.0 projects.

To obtain the installer and setup files for Kentico 8.1:

1. Download the [Kentico 8.1 installer](http://download.kentico.com/Kentico_8_1.exe).
2. Run **Kentico\_8\_1.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, the system performs certain tasks required to finalize the upgrade. This includes the import of new objects. Processing of the first request may take longer than usual.

### Object import

The upgrade procedure automatically imports new web part, widget, report and time zone objects. Once the upgrade is finished, please check the system’s **Event log** for any import errors between the _Upgrade - Start_ and _Upgrade - Finish_ events.

If you find import-related errors, open the **Sites** application, click **Import site or objects** and try to import the _upgrade\_80\_81.zip_ package manually.

### 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/k81/macro-expressions.md) chapter.

### SharePoint integration

The upgrade installs the new **SharePoint** module by default. See [Integrating SharePoint](https://docs.kentico.com/k81/integrating-3rd-party-systems/integrating-sharepoint.md) for more information.

If you plan to use the new module:

1. In the Kentico administration interface, open the **Modules** application.
2. Edit the **SharePoint** module.
3. Select the **Sites** tab and add your sites.

### 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**.

### File uploader styling

Kentico 8.1 uses a new file uploader based on HTML5 instead of the Silverlight uploader from previous versions. The new uploader has modified HTML markup that applies a different CSS class.

You may need to update your site's stylesheet after the upgrade if you use custom live site styling without linking the default **Skin.css** file (see [Designing websites using CSS](https://docs.kentico.com/k81/developing-websites/designing-websites-using-css.md) for more information). To style the uploader in your own stylesheet, define the following classes:

```css

.uploader-overlay-div {
  background: rgba(0, 0, 0, 0);
  overflow: hidden;
  opacity: 0;
  width: 100%;
  height: 100%;
  position: absolute;
  top: 0;
  left: 0;
}

.uploader-overlay-div > input[type="file"] {
  display: none;
}

```

You can adjust the styles of the classes to match the design of your website.