Version Specific Upgrades

This document covers specific upgrade steps if a version requires them. Most versions do not require specific upgrade steps and you will be able to upgrade directly from your current version.

This page is a work in progress. It will be updated as the software evolves.

Version Specific Upgrades

Use the information below to learn about any potential breaking changes and common pitfalls when upgrading your Umbraco CMS project.

If any specific steps are involved with upgrading to a specific version they will be listed below.

Use the general upgrade guide to complete the upgrade of your project.

Breaking changes

Umbraco 14

Below you can find the list of breaking changes introduced in Umbraco 14 CMS.

• Angular removed: A new backoffice built with Web Components, Lit, and fueled by the Umbraco UI Library

• Icons in the new backoffice are based on Lucide.

• Full TypeScript support for the Backoffice and all its APIs through a public npm package

• A management API documentation in Swagger - replacement for Controllers that were not restful

• Migration from Newtonsoft.Json to the System.Text.Json which removes Nested Content and Grid value converter and so on

• Nested Content and Grid Layout have been removed

• Legacy media picker has been removed

• Macros and Partial View Macros have been removed. Use partial views and/or blocks in the Rich Text Editor.

• XPath has been removed. An alternative is using the Dynamic Roots in the Multinode Treepicker and for ContentXPath the alternative is IContentLastChanceFinder.

• package-manifest is now umbraco.package.json

• Smidge has been removed from default installation along with RuntimeMinification setting. Smidge can be manually installed if needed and you can read the Smidge documentation on how to setup a similar setting to RuntimeMinification.

• New login screen

• Light, Dark or Contract Mode option has been added in the backoffice. You can choose your preffered mode from your profile information.

• UI Library and UI API external documentations.

In-depth and further breaking changes for v14 can be found on the CMS Github repository and on Our Website.

Umbraco 14 RC Versions

Below you can find the list of breaking changes introduced in Umbraco 14 RC release versions.

RC 2

Bellissima (Client) Breaking Changes since:

• #1690 - Bugfix: The modal context should update the entire value rather than updating it partially

• #1670 - Delete UmbInputListBaseElement

RC 1 First RC release - 17th of April.

Breaking changes since Beta 3:

• #1411 - Bugfix: Move To Entity Action (Part 1)

• #1568 - Feature/Content Editor Kind + Work for validation (take 3)

• #1591 - Bugfix: Duplicate to Entity Action (part 1)

Umbraco 14 Beta Versions

Below you can find the list of breaking changes introduced in Umbraco 14 Beta release versions.

Beta 3

Management API Breaking Changes:

• #16027 - Remove manifest validators

• #16026 - Remove remnants of the Angular implementation

• #16024 - Remove "additional data" from entities

• #15946 - Document version endpoints with async service

• #15923 - Convert Tourdata into a more generic concept

Bellissima (Client) Breaking Changes:

• #1455 - Workspace routable kind

• #1475 - Feature: Entity Workspace Context Token and Interface + preparation for Validation

• #1488 - Rename Settings Menu

• #1429 - Feature: Workspace breadcrumbs

• #1474 - Bugfix: Relation types

• #1502 - Feature/tracked references server update

• #1500 - Breaking: Rename save() to submit() for workspace contexts (Validation part 2)

• #1521 - Breaking: rename Umbraco controller methods

• #1391 - Bugfix: Rename file system file

• #1524 - Remove exports from packages/core/index.ts

• #1565 - Feature: Replace openapi-typescript-codegen with @hey-api/openapi-ts

• #1569 - Feature: Rename Resource class suffix to Service

• #1584 - UI Library 1.8.0-rc.1

Beta 2

There are a few breaking changes since Beta 1. Most of the changes concern property editors and getting them to work with migrations as well as new values.

• #1408 - Refactor: Workspace Collection Condition (plus new Context token)

• #1423 - Feature/individual publication modals

• #1439 - rename selectedIds + Corrections for Lit warnings

Management API Breaking Changes

• #15892 - Revoke previous sessions when AllowConcurrentLogins is false

• #15890 - Extend IContentEntitySlim

• #15891 - Remove Keep Alive Job

• #15887 - Workaround for failing entity tree children

• #15862 - Removed “type” from tree item response models

• #15856 - Remove duplicate pagination helper

Beta 1 Official release of Beta, 6th March 2023.

In-depth previous, further and other changes for v14 beta versions can be found on the Release Notes on the Umbraco.CMS.Backoffice repository.