--- title: Upgrading to Kentico 12 related: - https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-custom-code.md - https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-projects-under-source-control.md - https://docs.kentico.com/k12sp/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). > **Note:** **Kentico 12 Service Pack** > > If you already have Kentico 12 and wish to apply **Kentico 12 Service Pack**, you do NOT need to follow the upgrade process described on this page. > > You only need to apply **hotfix version 12.0.29** or newer to your project. See the [Hotfix instructions](https://docs.kentico.com/k12sp/installation/hotfix-instructions-kentico-12.md) to learn how to install the service pack via the hotfix. This page provides instructions for upgrading Kentico projects from version 11 to 12. 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) > **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/k12sp/installation/upgrading-to-kentico-12/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. ## Warning Using the [Export and Import](https://docs.kentico.com/k12sp/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 12. See [System requirements](https://docs.kentico.com/k12sp/installation/system-requirements.md) for details. The upgrade must be performed on a machine with a working Internet connection. **Note**: The upgrade must be applied to complete projects that use the standard folder structure (the _CMS_ and _Lib_ sub folders) and names of key files (the solution file, _csproj_ project file, _web.config_, _packages.config_, _GlobalAssemblyInfo.cs_). 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 11, 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. When processing the first request after the upgrade, the system performs certain tasks required to finish the upgrade, including the import of new objects. The same requirement applies even if you are only updating to a newer patch version by applying a [hotfix](https://devnet.kentico.com/download/hotfixes) to the upgraded project. ## 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 12 features and changes – see [Release notes - Kentico 12](https://docs.kentico.com/k12sp/release-notes-kentico-12.md#kentico-12.0-released-november-27-2018) for a comprehensive list. - If your Kentico project's Target framework version is NET Framework 4.6, the upgrade sets the version to 4.6.1 (the minimum .NET version supported by Kentico 12). Projects with a higher Target framework version are supported by the upgrade (the version remains unchanged). - The upgrade integrates third-party libraries by installing the following additional NuGet packages into the Kentico project (and their dependencies): - [DocumentFormat.OpenXml](https://www.nuget.org/packages/DocumentFormat.OpenXml) 2.7.2 - [linqtotwitter](https://www.nuget.org/packages/linqtotwitter/) 4.0.0 - [MaxMind.GeoIP2](https://www.nuget.org/packages/MaxMind.GeoIP2/) 3.0.0 - [OpenPop.NET](https://www.nuget.org/packages/OpenPop.NET/) 2.0.4.369 - [System.IO.Packaging](https://www.nuget.org/packages/System.IO.Packaging/) 4.0.0 > **Info:** If your Kentico project already contains a different version of one of these NuGet packages, the upgrade either updates the package to the required version (for older versions) or does not change the version (for newer versions). > > In both cases, a [binding redirect](https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/bindingredirect-element) is automatically added to the project's _web.config_ file for the related assembly (either from your old version to the required version, or from the required version to your newer version). - 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 12 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 12 remain in the file system, with an added _.deleted_ extension. These files are not included in the _CMSApp_ project in web application projects. - 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/k12sp/configuring-kentico/setting-up-web-farms.md) and [continuous integration](https://docs.kentico.com/k12sp/developing-websites/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 the previous version 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/k12sp/custom-development/developing-form-controls.md) objects are overwritten (both the source files and form control objects in the system). #### Content management - Obsolete MVC functionality related to the CMSApp\_MVC project was completely removed from the system. Page templates of the _MVC_ type are changed to the _Portal page_ type. MVC URL paths of pages are replaced by empty strings and all page aliases with the MVC Path type are removed. #### Social & Community - The _Friends_ and _Messaging_ features were removed from the system, along with all related components (web parts, widgets, email templates, form controls). See the [Removed web parts](#removed-web-parts) section for more detailed information. ## Installing the upgrade procedure 1. Download the [Kentico 12 upgrade](http://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_11_0_12_0.exe). 2. Run **Upgrade\_11\_0\_12\_0.exe**. 3. Install the upgrade procedure (the installer places the upgrade into the _C:\Program Files\Kentico\12.0\Upgrade110\_120_ folder by default). ## Steps before you start the upgrade ### Custom code analysis > **Info:** See the [Release notes](https://docs.kentico.com/k12sp/release-notes-kentico-12.md#releasenoteskentico12-breakingapi) for highlights of the breaking changes in the Kentico 12 API. If you have an [MVC site](https://docs.kentico.com/k12sp/developing-websites/mvc-development-overview.md) or if your Kentico project contains any custom code (including virtual objects such as [transformations](https://docs.kentico.com/k12sp/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-12) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-custom-code.md) to learn more. The tool has the following functionality: - Detects code that is no longer valid in version 12 - Provides recommendations for each occurrence of invalid code - Can automatically convert the majority of code to the Kentico 12 API The tool’s output will help you update the code of your projects after you perform the upgrade. ### Required .NET Compiler Platform Kentico 12 requires the [.NET Compiler Platform ('Roslyn')](https://github.com/dotnet/roslyn) compiler to run, provided by the [Microsoft.CodeDom.Providers.DotNetCompilerPlatform](https://www.nuget.org/packages/Microsoft.CodeDom.Providers.DotNetCompilerPlatform/) NuGet package. The upgrade automatically updates the package to version **2.0.1** (if necessary). The updated version no longer requires the **Microsoft.Net.Compilers** package as a dependency, and we recommend uninstalling this package (unless required by your custom functionality). ### 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/k12sp/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/k12sp/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/k12sp/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/k12sp/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/k12sp/configuring-kentico/working-with-object-versioning/objects-recycle-bin.md) - Previous [versions of objects](https://docs.kentico.com/k12sp/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. > **Note:** **Page version history and workflow** > > The instructions above only apply to the version history of non-page objects. > > If your website's content uses [workflow](https://docs.kentico.com/k12sp/configuring-kentico/configuring-the-environment-for-content-editors/configuring-workflows.md) (or page versioning without workflow), you do NOT need to clear the version history of pages before starting the upgrade. Existing page versions and pages under workflow should work correctly after performing the upgrade. ### 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/k12sp/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/k12sp/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts.md) and [activity](https://docs.kentico.com/k12sp/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/k12sp/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. ### Removed web parts The upgrade removes the following web parts: - Friends list - Friends viewer - Friends waiting for approval - Friendship management - My friends - My pending requests - Rejected friends - Request friendship - Contact list - Ignore list - Inbox - Messaging info panel - My messages - Outbox - Send message You need to replace or remove instances of these web parts on your site's page templates. Use the following process: 1. Open the **Web parts** application. 2. Select the given web part and view the **Usage** tab. 3. Remove or replace any occurrences of the web part on your site. 4. If a web part is used by a [widget](https://docs.kentico.com/k12sp/developing-websites/preparing-widgets-for-users.md) or [inherited web part](https://docs.kentico.com/k12sp/developing-websites/developing-web-parts/creating-inherited-web-parts.md), perform these steps for the given components (use the **Widgets** application for widgets). After you remove or replace all occurrences of a web part, we strongly recommend that you delete it in the **Web parts** application. > **Info:** The upgrade procedure deletes all source files of the listed web parts, but leaves their database records. If you do not manually delete them, these non-functional web parts and their categories may remain in your database after the upgrade, with a _(Removed)_ suffix added to the display name. ### Removed goo.gl URL shortener integration The upgrade removes the **goo.gl** [URL shortener](https://docs.kentico.com/k12sp/integrating-3rd-party-systems/integrating-social-media/setting-up-url-shorteners.md) for social media posts from the system. The Google URL Shortener service is [discontinued](https://developers.googleblog.com/2018/03/transitioning-google-url-shortener.html) and its API will stop working after March 30, 2019. Before starting the upgrade, make sure that the goo.gl URL shortener is not used: - In the **Settings** application, check the **Social marketing -> Default URL shortener** settings. If necessary, switch to a different URL shortener or select the _(do not shorten links)_ option. - In the **Workflows** application, check any [advanced workflows](https://docs.kentico.com/k12sp/configuring-kentico/configuring-the-environment-for-content-editors/configuring-workflows/designing-advanced-workflows.md) that contain **Publish to Facebook**, **Publish to Twitter** or **Publish to LinkedIn** steps. If necessary, edit the steps and switch their **URL shortener** property to a different shortener or select the _(do not shorten links)_ option. If you do not remove usage of the goo.gl URL shortener from your system, you may encounter errors when posting to social media after the upgrade. ## Applying the upgrade We strongly recommend using the [Kentico Upgrade Utility](https://docs.kentico.com/k12sp/external-utilities/kentico-hotfix-and-upgrade-utility.md) to perform the upgrade automatically. > **Info:** **Manual upgrade** > > If you cannot run the automatic upgrade utility, you can perform the upgrade manually. See [Upgrading Kentico manually](https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-kentico-manually.md). **Note**: Before you run the upgrade utility, close any instances of Visual Studio where the target Kentico solution is opened. 1. Open the folder where you installed the upgrade. 2. Run the **Kentico Upgrade Utility** (_Upgrade.exe)_. 3. Enter the path to your Kentico 11 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/k12sp/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 12 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 12, 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 12 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 12 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: 1. Edit the new web.config and transfer over any customizations and the connection string from the original web.config. 2. Move your original web.config to a different location. 3. Rename _web.config.new_ to _web.config_. Close the upgrade utility. ### Upgrading MVC projects For websites created using the [MVC development model](https://docs.kentico.com/k12sp/developing-websites/mvc-development-overview.md), you need to upgrade your Kentico administration application ([see above](#applying-the-upgrade)), and additionally update the Kentico code used by your MVC application: 1. Open your MVC application in Visual Studio. 2. Update your MVC project's **Target framework** version to _NET Framework 4.6.1_ or newer (if necessary). 3. Right-click your MVC project in the **Solution Explorer** and select **Manage NuGet Packages**. 4. Uninstall all Kentico 11 integration packages for MVC development – _Kentico.Web.Mvc_, _Kentico.Content.Web.Mvc_, _Kentico.Ecommerce_, etc. 5. Install the **Kentico.AspNet.Mvc** NuGet package (use version 12.0.0 until you apply a [hotfix](https://docs.kentico.com/k12sp/installation/hotfix-instructions-kentico-12.md) to your upgraded Kentico project). The new _Kentico.AspNet.Mvc_ package combines the functionality of the original Kentico 11 packages. In many cases, the API of the packages was replaced by API provided as part of the _Kentico.Libraries_ package, which is automatically installed as a dependency. We strongly recommend that you additionally: - Read about breaking changes related to the packages in the [release notes](https://docs.kentico.com/k12sp/release-notes-kentico-12.md#nuget-packages-for-mvc-development). - Run the [code upgrade tool](https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-custom-code.md) for your MVC project and use the provided information to update your code. ### Upgrading separated on-line marketing databases If your project uses a [separated on-line marketing database](https://docs.kentico.com/k12sp/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\12.0\Upgrade110\_120_ 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 code according to the new API of Kentico 12, including: - Code files in [MVC projects](https://docs.kentico.com/k12sp/developing-websites/mvc-development-overview.md) that use the Kentico API - Custom or customized code files in the Kentico web project - Virtual objects in Kentico, such as [transformations](https://docs.kentico.com/k12sp/developing-websites/loading-and-displaying-data-on-websites/writing-transformations.md) and [page layouts](https://docs.kentico.com/k12sp/developing-websites/developing-websites-using-portal-engine/editing-page-layouts.md) (used by Portal Engine sites) Use the output of the Kentico [code upgrade tool](https://docs.kentico.com/k12sp/installation/upgrading-to-kentico-12/upgrading-custom-code.md) to find occurrences of invalid code and recommendations on how to fix or replace them. **Tip**: For Portal Engine sites, enable [Deployment mode](https://docs.kentico.com/k12sp/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](https://devnet.kentico.com/documentation/api-changes/kentico-12) ### NuGet package consolidation The upgrade updates the version of some of the NuGet packages installed within the Kentico web project. If your project already contains a different version of one of these NuGet packages, the upgrade either updates the package to the required version (for older versions) or does not change the version (for newer versions). In both cases, a [binding redirect](https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/bindingredirect-element) is automatically added to the project's _web.config_ file for the related assembly (either from your old version to the required version, or from the required version to your newer version). If you have any custom projects within the solution that use the same packages or any of their dependencies, you need to consolidate the package versions: 1. Right-click the solution in the **Solution Explorer** and select **Manage NuGet Packages for Solution**. 2. Select the **Consolidate** tab, and make sure your custom projects use the same package versions as the Kentico web project _(CMSApp_ or _CMS)._ If your Kentico project uses a higher **Target framework** than _.NET Framework 4.6.1_, we strongly recommend that you consolidate the target framework version for all installed NuGet packages: 1. Open your Kentico project in Visual Studio. 2. Open the **Package Manager Console** (under **Tools > NuGet Package Manager**). 3. Run the following commands: ```csharp Uninstall-Package -Id Rx-Main -Force -RemoveDependencies; Uninstall-Package -Id linqtotwitter -Force; Update-Package -reinstall; Install-Package -Id linqtotwitter -Version 4.0.0 ``` The [Update-Package](https://docs.microsoft.com/en-us/nuget/tools/ps-ref-update-package) command reinstalls all NuGet packages with the appropriate target framework version for your project. The other _Uninstall-Package_ and _Install-Package_ commands manually remove and add packages that could cause errors during the reinstallation. ### 404 handling on MVC sites The Kentico 12 NuGet packages for MVC sites no longer provide the _NotFoundHandler_ feature for handling of errors with the 404 status code. Instead, we recommend that you set up [handling of 404 errors via IIS](https://docs.kentico.com/k12sp/securing-websites/developing-secure-websites/handling-error-messages-securely/handling-404-errors-in-mvc-applications.md). ### Web farm synchronization tasks Kentico 12 introduces a new way of registering and creating web farm synchronization tasks. If you are using any custom web farm synchronization tasks in your environment, you need to refactor your custom code to comply with the new standard. See [Creating custom web farm synchronization tasks](https://docs.kentico.com/k12sp/configuring-kentico/setting-up-web-farms/creating-custom-web-farm-synchronization-tasks.md) for more information and a sample implementation of the new approach.  ### Obsolete Attachment API The **Attachment** class from the _CMS.DocumentEngine_ namespace of the Kentico API is now obsolete and should be replaced with the _DocumentAttachment_ class in any custom code. If you have any page types with _File_ or _Attachment_ fields and use [generated API classes](https://docs.kentico.com/k12sp/developing-websites/generating-classes-for-kentico-objects.md) to work with them, re-generate the given Info and InfoProvider classes. Alternatively, you can replace occurrences of the _Attachment_ class in the code of these page types manually. ### Assembly references Kentico 12 brings the following assembly changes: - **CMS.CKEditor.Web.UI.dll** merged into **CMS.Base.Web.UI.dll** - **CMS.Localization.dll** merged into **CMS.Globalization.dll** - **CMS.ModuleLicenses.dll** merged into **CMS.Modules.dll** - **CMS.ModuleLicenses.Web.UI.dll** renamed to **CMS.Modules.Web.UI.dll** You need to remove any manually added references from custom projects to the old assemblies. If necessary, add new references to the assemblies into which the code was merged. The changes do not impact the related API and namespaces. ### Automated tests The Kentico 12 version of the **Kentico.Libraries.Tests** NuGet package (_CMS.Tests_ library) no longer supports the **Microsoft unit test** framework. If you have any tests built with this framework, you need to rewrite them to either use the [NUnit](https://github.com/nunit/docs/wiki) testing framework or to work without the _CMS.Tests_ library. For more information, see the [Writing automated tests](https://docs.kentico.com/k12sp/custom-development/writing-automated-tests.md) chapter. ### Kentico 12 setup files The upgrade converts your web projects to version 12, 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/k12sp/external-utilities.md), sample files, and allow you to install new Kentico 12 web projects. To obtain the installer and setup files for Kentico 12: 1. Download the [Kentico 12 installer](http://download.kentico.com/Kentico_12_0.exe). 2. Run **Kentico\_12\_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 **Important**: This step must be performed **before you apply any hotfixes** to the upgraded project. Open the upgraded website in a browser. For [MVC sites](https://docs.kentico.com/k12sp/developing-websites/mvc-development-overview.md), you need to open the URL of the Kentico administration interface (not the live site presented by the MVC application). 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. Once the website loads, sign 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\_110\_120.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 12 licenses for the domains used by your sites: 1. In the Kentico administration interface, open the **Licenses** application. 2. Delete the old version 11 licenses. 3. Click **New license** to add your licenses for version 12. ### Macros To ensure that macros and the administration interface work correctly after the upgrade: 1. Sign 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/k12sp/macro-expressions.md) chapter. ### Web farms The upgrade procedure automatically disables [web farm](https://docs.kentico.com/k12sp/configuring-kentico/setting-up-web-farms.md) functionality. If your Kentico instance runs on a web farm or you use the MVC development model, 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/k12sp/configuring-kentico/setting-up-web-farms/configuring-web-farm-servers.md). 4. Click **Save**. ### MVC sites – Presentation URL In Kentico 12, the [Presentation URL](https://docs.kentico.com/k12sp/configuring-kentico/managing-sites/setting-domain-names-for-sites.md#setting-the-domain-for-content-only-sites) of MVC sites must include the URL scheme (protocol). If you have an MVC (content-only) site, make sure that it fulfills this requirement: 1. In the Kentico administration interface, open the **Sites** application. 2. Edit your MVC site. 3. If necessary, add the URL scheme into the **Presentation URL** value. For example: _https://www.mysite.com_ 4. Click **Save**. ### Geolocation The geolocation feature was updated to work with [Maxmind's GeoIP2 Databases](https://www.maxmind.com/en/geoip2-services-and-databases). If you use geolocation, you need to add the newer GeoLite2 or GeoIP2 database files into your web project. See [Using geolocation for contacts](https://docs.kentico.com/k12sp/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-contacts/using-geolocation-for-contacts.md) for detailed instructions. ### UI personalization If you have [UI personalization](https://docs.kentico.com/k12sp/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.). ## 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\12.0\Upgrade110\_120_ by default), and copy the **CMS\CMS\CMSSiteUtils\Import\Upgrade\_110\_120.zip** file into the **CMS\CMSSiteUtils\Import** folder of the new Kentico 12 project. 7. Perform all relevant [steps after the upgrade](#steps-after-performing-the-upgrade).