--- title: Upgrading to Xperience 13 related: - https://docs.kentico.com/13/installation/upgrading-to-xperience-13/upgrading-custom-code.md - https://docs.kentico.com/13/installation/upgrading-to-xperience-13/upgrading-projects-under-source-control.md - https://docs.kentico.com/13/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:** **Xperience 13 Refresh releases** > > If you already have Xperience 13 and wish to apply a **Refresh** release, do NOT follow the upgrade process described on this page. > > You only need to apply the **appropriate hotfix version** to your project. See the [Hotfix instructions](https://docs.kentico.com/13/installation/hotfix-instructions-xperience-13.md) to learn how to install Refreshes via the hotfix. This page provides instructions for upgrading projects from version _Kentico 12 Service Pack_ to _Xperience 13_. 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 administration and live site projects](#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/13/installation/upgrading-to-xperience-13/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/13/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 following: - All [system requirements](https://docs.kentico.com/13/installation/system-requirements.md) of Xperience 13. - **Note**: Microsoft SQL Server 2008 R2 is no longer supported for Xperience databases. You need to upgrade your database server (and database compatibility level) to version 2012 or newer before you start the Xperience upgrade. - The machine where you perform the upgrade must have a working Internet connection. - Xperience 13 only supports the MVC and ASP.NET Core development models. **Upgrading Portal Engine sites is not possible**. - The upgrade to Xperience 13 is not supported for projects of the _web site_ type. In these cases, only run the database upgrade scripts, then install a new Xperience 13 project and manually transfer any customizations (or convert your administration project to a _web application_). - The upgrade does not support installations with removed (separated) modules. To perform the upgrade, you need to use the Kentico 12 Service Pack installer utility to add any missing modules. - The upgrade is not possible if the project contains obsolete forms that are not based on the MVC Form builder (forms created in Kentico version 11 or older). In these cases, you need to back up any recorded form data and remove the forms. You can create a new form based on the MVC Form builder and migrate the data. **Note**: The upgrade must be applied to complete administration 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 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 12, 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 Xperience 13 features and changes – see [Release notes - Xperience 13](https://docs.kentico.com/13/release-notes-xperience-13.md) for a comprehensive list. - The Portal Engine and ASPX template development models for websites are no longer supported. Related features and components (web parts, widgets, page templates, controls, etc.) are removed from the system. - Web parts can no longer be used to build website pages. They remain in the system as components for administration interface pages. - Portal Engine page templates can no longer be assigned to website pages. They remain in the system as a way to build administration interface pages. Ad-hoc templates dedicated to individual pages are no longer supported. When upgrading projects, all page templates except for UI and dashboard templates are removed, and any ad-hoc UI templates are converted to global shared templates. - All support for the original Portal Engine widgets was removed for live site content. This includes editor, user and group widgets, as well as inline widgets (adding widgets into editable text areas via the editor). Widgets can still be used on dashboards within the administration interface. - If your project's Target framework version is lower than NET Framework 4.8, the upgrade sets the version to 4.8 (the minimum .NET version supported by Xperience 13). - The upgrade integrates third-party libraries by installing and updating NuGet packages (and their dependencies) in the Xperience project. > **Info:** 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). - Custom files in the original project are transferred to the upgraded project. - Customized Xperience 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 Xperience 13 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 Xperience 13 remain in the file system, with an added _.deleted_ extension. These files are not included in the _CMSApp_ project. - If your Xperience 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 Xperience database (_dbo_ by default). - The upgrade disables [web farm](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms.md) and [continuous integration](https://docs.kentico.com/13/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/13/custom-development/extending-the-administration-interface/developing-form-controls.md) objects are overwritten (both the source files and form control objects in the system). #### Content management - Xperience 13 no longer contains functionality for files represented as pages in the content tree via the _CMS.File_ page type. The upgrade preserves the _CMS.File_ page type and any existing pages. However, there is no longer any "special system handling" for _CMS.File_ pages and they behave as standard pages with file attachments. - Due to the removal of community features and groups, all group media libraries are converted to regular media libraries by the upgrade. #### On-line marketing - [Marketing automation](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation.md) – the upgrade makes the following changes for [steps](https://docs.kentico.com/13/on-line-marketing-features/managing-your-on-line-marketing-features/marketing-automation/working-with-the-automation-process-designer.md) within existing marketing automation processes: - Standard – renamed to _Approve progress_. - First win – renamed to _If/Else_. - Condition – automatically converted to steps of the _If/Else_ type. - Multi-choice – existing occurrences remain in processes, but are considered as obsolete. Can no longer be added directly, but existing steps can be cloned. We recommend using the _If/Else_ step type to create automatic branching conditions. - User choice – renamed to _Manual choice_. - Start process – renamed to _Start another process_. #### Email templates - The upgrade removes the _Membership - Forgotten password (obsolete)_ [email template](https://docs.kentico.com/13/configuring-xperience/managing-email-templates.md), the related macro resolver, and the _Forgotten password_ template type. This template was obsolete and no longer used by the system's [password reset functionality](https://docs.kentico.com/13/securing-websites/designing-secure-websites/securing-user-accounts-and-passwords/configuring-password-resets-for-xperience-administration.md). Any custom email templates assigned to the _Forgotten password_ template type remain in the system, but macros that rely on the removed resolver will no longer work correctly. Such templates are marked with the _"(obsolete)"_ suffix in their display name. #### Social & Community - The upgrade removes the following community features from the system, along with all related components (web parts, widgets, email templates, form controls, settings) and API: - Abuse report - Bad words - Blogs - Chat - Content rating - Events - Forums - Flood protection - Groups - Message boards - Polls - User badges and activity points - User contribution web parts ## Installing the upgrade procedure 1. Download the [Xperience 13 upgrade](https://download.kentico.com/CMSUpgrades/Upgrade/Upgrade_12_0_13_0.exe). 2. Run **Upgrade\_12\_0\_13\_0.exe**. 3. Install the upgrade procedure (the installer places the upgrade into the _C:\Program Files\Kentico\13.0\Upgrade120\_130_ folder by default). ## Steps before you start the upgrade ### Custom code analysis > **Info:** See the [Release notes](https://docs.kentico.com/13/release-notes-xperience-13.md#releasenotesxperience13-breakingapi) for highlights of the breaking changes in the Xperience 13 API. We strongly recommend using the **Xperience code upgrade tool** before you start the upgrade procedure. Download the tool from the [API Changes](https://devnet.kentico.com/documentation/api-changes/) page on the DevNet portal. See [Upgrading custom code](https://docs.kentico.com/13/installation/upgrading-to-xperience-13/upgrading-custom-code.md) to learn more. The tool has the following functionality: - Detects code that is no longer valid in Xperience 13 - Provides recommendations for each occurrence of invalid code - Can automatically convert the majority of code to the Xperience 13 API The tool’s output will help you update the code of your projects after you perform the upgrade. ### Required .NET Compiler Platform Xperience 13 requires the [.NET Compiler Platform (](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. ### Removed Portal Engine functionality Due to the removal of the Portal Engine development model for live site pages, the upgrade removes the following objects and functionality. We recommend that you **back up any relevant code or data that you store in the objects**, since it will be deleted after the upgrade. - All Portal Engine page templates except for UI and dashboard templates. Any ad-hoc UI templates are converted to global shared templates. - Transformations of **ASCX**, **XSLT**, and **jQuery** types. You can create equivalent [macro-based transformations](https://docs.kentico.com/13/macro-expressions/writing-transformations-for-macros.md) if necessary. - Device profiles and device profile layouts. ### Alternative URLs The maximum length of [alternative URLs](https://docs.kentico.com/13/managing-website-content/working-with-pages/managing-page-urls.md) was reduced to 400 characters. You need to manually shorten all alternative URLs longer than 400 characters before performing the upgrade. The presence of longer alternative URLs will cause the upgrade process to fail. ### 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/13/deploying-websites/deploying-sites-to-a-live-server/deployment-mode-for-administration-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/13/deploying-websites/content-staging.md) or the [integration bus](https://docs.kentico.com/13/integrating-3rd-party-systems/using-the-integration-bus.md), you need to synchronize all staging and integration tasks before starting the upgrade procedure. Synchronization of existing tasks from older Kentico versions may fail after you perform the upgrade. To perform the synchronization, use the **Staging** or **Integration bus** applications. If you have the **Settings -> Versioning & Synchronization -> Staging -> Log export tasks** setting enabled, the system logs _delete tasks_ when objects are deleted. These tasks can then be included in [export](https://docs.kentico.com/13/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/13/configuring-xperience/working-with-object-versioning/objects-recycle-bin.md) - Previous [versions of objects](https://docs.kentico.com/13/configuring-xperience/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/13/configuring-xperience/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/13/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/13/on-line-marketing-features/managing-your-on-line-marketing-features/contact-management/working-with-contacts.md) and [activity](https://docs.kentico.com/13/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/13/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 Xperience database tables If you are using full-text search catalogs for any Xperience 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 ### Upgrading the administration project We strongly recommend using the [Kentico Upgrade Utility](https://docs.kentico.com/13/external-utilities/kentico-xperience-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 Xperience manually](https://docs.kentico.com/13/installation/upgrading-to-xperience-13/upgrading-xperience-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 12 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/13/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). 6. Click **Switch to advanced mode** and disable the **Rebuild web project** option. This is necessary because the project could contain certain files (introduced by later K12 hotfixes) that will not be compilable immediately after the upgrade is applied. > **Note:** **Warning**: If you enable the **Overwrite all files** option in _advanced mode_, the upgrade replaces all project files with the default Xperience 13 files, regardless of customizations. This includes the **web.config** file, which you need to configure again after applying 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 Xperience 13 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 Xperience 13 remain in the file system, with an added _.deleted_ extension. These files are not included in the _CMSApp_ project. 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_. 11. If your project contains custom code that is no longer supported in Xperience 13, you need to resolve these code changes before rebuilding the project. 12. **Rebuild** your administration project. Close the upgrade utility. ### Upgrading MVC projects You also need to upgrade the Xperience code used by the MVC application that provides your live site: 1. Open your MVC application in Visual Studio. 2. Update your MVC project's **Target framework** version to _NET Framework 4.8_. 3. Right-click your MVC project in the **Solution Explorer** and select **Manage NuGet Packages**. 4. Uninstall all Kentico 12 integration packages for MVC development – _Kentico.AspNet.Mvc, etc._ 5. Install the **Kentico.Xperience.AspNet.Mvc5** NuGet package (use version 13.0.0 until you apply a [hotfix](https://docs.kentico.com/13/installation/hotfix-instructions-xperience-13.md) to your upgraded Xperience project). 6. Clean your project's output folder (_\~/bin/_ by default). 7. **Rebuild** the solution. We strongly recommend that you additionally: - Read about breaking changes related to the packages in the [release notes](https://docs.kentico.com/13/release-notes-xperience-13.md#nuget-packages). - Run the [code upgrade tool](https://docs.kentico.com/13/installation/upgrading-to-xperience-13/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/13/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\13.0\Upgrade120\_130_ 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 Xperience database) 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 Xperience administration interface. ### API changes You need to update your code according to the new API of Xperience 13, including: - Code files in [MVC projects](https://docs.kentico.com/13/developing-websites/mvc-development-overview.md) that use the Xperience API - Custom or customized code files in the Xperience web project Use the output of the Xperience [code upgrade tool](https://docs.kentico.com/13/installation/upgrading-to-xperience-13/upgrading-custom-code.md) to find occurrences of invalid code and recommendations on how to fix or replace them. You can also search for specific API resolutions on the [DevNet portal](https://devnet.kentico.com/documentation/api-changes) ### NuGet package updates All [NuGet packages](https://docs.kentico.com/13/developing-websites/starting-with-mvc-development/installing-xperience-integration-packages.md) used for [MVC development](https://docs.kentico.com/13/developing-websites/mvc-development-overview.md) and general integration of the Xperience API were renamed (rebranded). When upgrading MVC projects, custom assemblies, or any external applications that use the packages, you need to uninstall the original Kentico 12 packages and replace them with the equivalent packages for Xperience 13. | Kentico 12 | Xperience 13 | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Kentico.AspNet.Mvc | Kentico.Xperience.AspNet.Mvc5 | | Kentico.AspNet.Mvc.Libraries | Kentico.Xperience.AspNet.Mvc5.Libraries | | Kentico.Libraries | Kentico.Xperience.Libraries | | Kentico.Libraries.Web.UI | The package was removed. The contained _Web.UI_ libraries are only intended for use within the Xperience administration application. If necessary, you can access the libraries in the _Lib_ folder of Xperience projects. | | Kentico.LanguagePack.English | The package was removed. Localization files are now part of application assemblies (included as part of the _Kentico.Xperience.AspNet.Mvc5.Libraries_ package). | | Kentico.Libraries.Tests | Kentico.Xperience.Libraries.Tests | | Kentico.Glimpse | Kentico.Xperience.Glimpse | ### External authentication packages If your live site project uses [external authentication](https://docs.kentico.com/13/managing-users/user-registration-and-authentication/configuring-external-authentication.md) and the **Microsoft.Owin.Security** NuGet packages that provide the required middleware components, you need to update these packages to version _4.0.0_ or newer. Older versions are not compatible with Xperience 13. ### Consolidation of administration NuGet packages The upgrade updates the version of some of the NuGet packages installed within the Xperience administration 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 Xperience _CMSApp_ web project\*.\* If you update the Target framework version for a project, we also recommend consolidating all installed NuGet packages to target the same version: 1. In Visual Studio, open the **Package Manager Console** (under **Tools > NuGet Package Manager**). 2. 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. ### Assembly references Xperience 13 brings the following assembly changes: - **ThoughtWorks.QRCode.dll** removed - **CMS.PortalEngine.dll** and **CMS.OutputFilter.dll** merged into **CMS.PortalEngine.Web.UI.dll** You need to remove any manually added references from custom projects to removed 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. ### Xperience 13 setup files The upgrade converts your web projects to version 13, but does not provide the associated setup files (i.e. the Xperience program files that are separate from individual web projects). The setup files contain [external utilities](https://docs.kentico.com/13/external-utilities.md), sample files, and allow you to install new Xperience 13 web projects. To obtain the installer and setup files for Xperience 13: 1. Download the [Xperience 13 installer](https://download.kentico.com/Xperience_13_Refresh14.exe) (this installer includes Refresh 13 – hotfix version 13.0.197). 2. Run **Xperience\_13\_Refresh13.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. You need to open the URL of the Xperience administration interface (not the live site). 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\_120\_130.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](https://devnet.kentico.com/support) and provide the details of the errors. ### Licenses You need to add Xperience 13 licenses for the domains used by your sites: 1. In the Xperience administration interface, open the **License keys** application. 2. Delete the old version 12 licenses. 3. Click **New license** to add your licenses for version 13. ### Macros To ensure that macros and the administration interface work correctly after the upgrade: 1. Sign in to the Xperience 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**. After the upgrade, certain macros in the system may be moved or marked obsolete. Follow the instruction provided by the macro report tool to resolve the identified issues. If a macro method is reported as removed, and you wish to continue using it, you need to develop your own [custom implementation](https://docs.kentico.com/13/macro-expressions/extending-the-macro-engine/registering-custom-macro-methods.md). For more information, see the [Macro expressions](https://docs.kentico.com/13/macro-expressions.md) chapter. ### Web farms The upgrade procedure automatically disables [web farm](https://docs.kentico.com/13/configuring-xperience/setting-up-web-farms.md) functionality. You need to enable web farms again after you complete the upgrade. We recommend that you enable the web farm on **one server** or instance and after that add the remaining servers to the web farm. 1. In the Xperience administration interface, open the **Settings** application. 2. Expand the **Versioning & Synchronization -> Web farm** category. 3. Select the **Web farm mode**: - Automatic (recommended) – 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/13/configuring-xperience/setting-up-web-farms/configuring-web-farm-servers.md). 4. Click **Save**. ### Switching to content tree-based routing [Content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing.md) is a new Xperience feature that enables automatic generation of URLs for pages based on their position in the content tree. Another new feature, managed through the [Former URLs](https://docs.kentico.com/13/managing-website-content/working-with-pages/managing-page-urls.md) application, enables automatic tracking of changes made to the URL paths of pages in the content tree and handles redirection from the pages' old URLs to the current URLs. If you want to enable content tree-based routing on a site that uses [customrouting](https://docs.kentico.com/13/developing-websites/implementing-routing/custom-routing-using-url-patterns.md) based on page type URL patterns, you can manually preserve the old URLs as [former URLs](https://docs.kentico.com/13/managing-website-content/working-with-pages/managing-page-urls.md#former-urls) by running a prepared code snippet. This ensures that pages remain accessible under their old URLs and allows for a smoother transition to the new routing type. See [Enabling content tree-based routing](https://docs.kentico.com/13/developing-websites/implementing-routing/content-tree-based-routing/enabling-content-tree-based-routing.md) for more information. ### UI personalization If you have [UI personalization](https://docs.kentico.com/13/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.). ### Applying the latest hotfix After you finish upgrading to version 13.0.0, update the project to the latest [hotfix version](https://docs.kentico.com/13/installation/hotfix-instructions-xperience-13.md). Xperience 13 has a large number of released refreshes and hotfixes, which add many new features and ensure that the application is secure. ## 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\13.0\Upgrade120\_130_ by default), and copy the **CMS\CMS\CMSSiteUtils\Import\Upgrade\_120\_130.zip** file into the **CMS\CMSSiteUtils\Import** folder of the new Xperience 13 project. 7. Perform all relevant [steps after the upgrade](#steps-after-performing-the-upgrade).