> For the complete documentation index, see [llms.txt](https://docs.umbraco.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbraco.com/umbraco-cms/19.latest/get-started/upgrading-and-migrating/version-specific.md).
# Breaking Changes Overview
Breaking changes introduced in each major version of Umbraco CMS, with notes on what to update when upgrading.
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](/umbraco-cms/19.latest/get-started/upgrading-and-migrating/upgrade-details.md) to complete the upgrade of your project.
## Preparation for Upgrade
Before running the upgrade, consider the following:
### Upgrade from Umbraco 16.4 or later
Umbraco 19 can only upgrade from Umbraco 16.4 or later, because it doesn't include the migrations from Umbraco 13 to 17. If your project runs an earlier version, upgrade to Umbraco 17 first. Umbraco 17 is the latest Long-term Support (LTS) version.
If you upgrade from Umbraco 17, review the Umbraco 18 breaking changes as well as the Umbraco 19 ones. See also [If you upgrade from Umbraco 17](#if-you-upgrade-from-umbraco-17) below.
### Back up your database
Take a backup of your database before you upgrade. Once the Umbraco 19 upgrade has started, Umbraco 18 can no longer open the database. Restoring the backup is the only way back.
### Resolve obsolete warnings
Umbraco 19 removes around 400 members that were marked as obsolete in earlier versions. Before you upgrade, update to the latest Umbraco 17 or 18 patch release and build your solution. Fix every obsolete warning that mentions removal in Umbraco 19. The warning text names the replacement to use.
### Packages
Check that each package you depend on has a release that supports Umbraco 19.
### Install .NET 11
Umbraco 19 runs on .NET 11. Before you upgrade:
* Install the [.NET 11 SDK](https://dotnet.microsoft.com/en-us/download/dotnet/11.0) on development and build machines.
* Confirm that your hosting environment supports the .NET 11 runtime.
* Change the `TargetFramework` in each project file from `net10.0` to `net11.0`.
For other effects of the .NET 11 upgrade, see the [.NET 11 entry](#net-11) under Breaking changes.
### Check your imaging HMAC secret key
.NET 11 rejects Base64 values that aren't in canonical form. Umbraco reads the `Umbraco:CMS:Imaging:HMACSecretKey` setting as Base64. A non-canonical key stops the site from starting.
Keys generated by Umbraco are always canonical. Keys pasted by hand or produced by another tool might not be. A key is canonical when decoding it and encoding it again returns the same string.
To fix a non-canonical key, correct its final character or generate a new key. Correcting the final character keeps the decoded bytes the same, so existing signed image URLs stay valid. For example, a key ending in `zx==` becomes `zw==`.
For more information, see the [Hash-based Message Authentication Code (HMAC) secret key](/umbraco-cms/19.latest/develop-with-umbraco/configuration/imagingsettings.md#hash-based-message-authentication-code-hmac-secret-key) section of the Imaging settings article.
{% hint style="info" %}
Microsoft is reviewing this .NET 11 behavior before the final release. Follow [dotnet/runtime#133495](https://github.com/dotnet/runtime/issues/133495) for the outcome.
{% endhint %}
### Plan the move from Examine to Umbraco Search
For most projects with custom search code, this is the largest upgrade task. Umbraco 19 removes the built-in Examine integration. Search now runs through Umbraco Search, with Examine as the default search provider.
Code that uses `IExamineManager`, custom Examine indexes, or index value factories must move to the Umbraco Search APIs. The built-in indexes also have new names.
Review your search code before you upgrade, and plan to rebuild the indexes afterwards. For details, see the [Examine integration replaced by Umbraco Search](#examine-integration-replaced-by-umbraco-search) entry and the [Search](/umbraco-cms/19.latest/develop-with-umbraco/search.md) documentation.
### Update backoffice extensions that use access tokens
The backoffice now authenticates with a cookie and no longer exposes access tokens to the browser. Backoffice extensions that read or refresh tokens, for example with `getLatestToken()`, stop working.
Check your own extensions and make sure the packages you use have releases for Umbraco 19. For how to make authenticated requests, see the [Fetch API](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/foundation/fetching-data/fetch-api.md#authenticate-requests-to-umbraco) article.
### Set the database command timeout explicitly
In Umbraco 17 and 18, `Connect Timeout` in the connection string was also used as the command timeout. Umbraco 19 removes that fallback, so the command timeout drops to the provider default of 30 seconds.
If your site logs a deprecation warning about this at startup, set `Command Timeout` in the connection string before you upgrade. You can also use the `Umbraco:CMS:Global:DatabaseCommandTimeout` setting. For more information, see the [Database timeouts](/umbraco-cms/19.latest/develop-with-umbraco/configuration/connectionstringssettings.md#database-timeouts) section.
### Plan for deployment artifacts
The upgrade moves some Data Types to new property editor aliases and configuration. Umbraco Deploy and uSync files exported before the upgrade still contain the old aliases. Importing them after the upgrade can put a Data Type back on the old property editor.
Upgrade all environments, and use versions of your deployment tools that support Umbraco 19. Be careful of this change if you import artifacts exported from an Umbraco 17 or 18 environment.
### If you upgrade from Umbraco 17
The following Umbraco 18 change also applies when you upgrade directly from Umbraco 17.
#### Empty the media recycle bin
From Umbraco 18, the `EnableMediaRecycleBinProtection` setting defaults to `true`. With this enabled, media files moved to the recycle bin are renamed with a `.deleted` suffix. They are renamed back on restore. Emptying the media recycle bin before upgrading avoids any uncertainty around the state of files already in the bin.
For details, see the entry on `EnableMediaRecycleBinProtection` in the Umbraco 18 breaking changes.
## Breaking changes
Umbraco 19
### .NET 11
Umbraco 19 targets .NET 11. All projects must target `net11.0`, and hosting environments need the .NET 11 runtime. Review Microsoft's [breaking changes in .NET 11](https://learn.microsoft.com/en-us/dotnet/core/compatibility/11) for changes that affect your own code.
The following .NET 11 changes are the most likely to affect an Umbraco project:
* **Strict Base64 decoding**: values with non-zero padding bits are rejected. This can stop a site with a hand-made imaging HMAC secret key from starting. See [Check your imaging HMAC secret key](#check-your-imaging-hmac-secret-key).
* **Exact double-to-decimal conversion**: casting a `double` to `decimal` now keeps the exact binary value. For example, `(decimal)1.65` becomes `1.6499999999999999111821580300m`. Review code that casts `double` values to `decimal` and then compares or validates them.
* **`Microsoft.OpenApi` 3.x**: `Microsoft.AspNetCore.OpenApi` 11 requires `Microsoft.OpenApi` 3.10 or later. Custom OpenAPI transformers might need updates. For example, the request and response `Content` is now `IDictionary`.
* **Packages in the shared framework**: `Microsoft.Extensions.Options`, `Microsoft.Extensions.Hosting.Abstractions`, `Microsoft.Extensions.Configuration.Abstractions` and `Microsoft.Extensions.Caching.Abstractions` now ship with .NET. Remove direct package references to them to avoid the `NU1510` build warning.
#### Runtime async
Umbraco is compiled with [runtime async](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-11/runtime#runtime-async) enabled. With this preview feature, the .NET runtime handles async methods instead of compiler-generated state machines. Microsoft lists cleaner stack traces, better debugging, and lower overhead as the benefits.
You don't need to change your own projects. Stack traces from Umbraco code can look different from earlier versions. To opt your own projects in, add the following to your project file or `Directory.Build.props`:
```xml
$(Features);runtime-async=on
```
See [#23955](https://github.com/umbraco/Umbraco-CMS/pull/23955) and [#24109](https://github.com/umbraco/Umbraco-CMS/pull/24109).
### Examine integration replaced by Umbraco Search
Umbraco Search, previously the separate `Umbraco.Cms.Search` package, is now part of Umbraco. It's the only search layer for the backoffice, the Delivery API, and templates. Examine, upgraded to version 4, is the default search provider and needs no separate installation. Another search provider can replace it.
The previous Examine integration in Umbraco has been removed. The changes you need to make:
* **Code that uses Examine directly**: `IExamineManager`, custom Examine indexes, and index value factories must move to the Umbraco Search APIs. Use `ISearcher` to query and `IIndexer` to index. See [Getting started with search](/umbraco-cms/19.latest/develop-with-umbraco/search/getting-started.md) and [Extending the Examine search provider](/umbraco-cms/19.latest/develop-with-umbraco/search/extending-search/examine-search-provider.md).
* **Index names**: the built-in indexes are now `Umb_PublishedContent`, `Umb_Content`, `Umb_Media` and `Umb_Members`. Update code that looks up an index by name. After upgrading, check the indexes in the **Search** section and rebuild them if needed. See [Search in the backoffice](/umbraco-cms/19.latest/develop-with-umbraco/search/backoffice.md).
* **`IPublishedContentQuery`**: the `Search` overloads that take an Examine `IQueryExecutor` have been removed. The unused `loadedFields` parameter has also been removed from the remaining `Search` methods. Use `ISearcher` for anything beyond a basic text search. See [IPublishedContentQuery](/umbraco-cms/19.latest/develop-with-umbraco/templating-and-rendering/querying/ipublishedcontentquery.md).
* **Search section extensions**: projects that extended the backoffice of the separate Umbraco Search package must update the extension aliases. For example, `Umbraco.Search.Workspace.Root` is now `Umb.Workspace.SearchRoot`. `Umbraco.Search.Workspace` is now `Umb.Workspace.SearchIndex`. Import the exported constants instead of typing the aliases.
The articles under [Searching with Examine](/umbraco-cms/19.latest/develop-with-umbraco/application-code/examine.md) describe the previous integration. See [#23321](https://github.com/umbraco/Umbraco-CMS/pull/23321) and [#23911](https://github.com/umbraco/Umbraco-CMS/pull/23911).
### Cookie-based authentication for the backoffice
The backoffice no longer uses client-side OAuth tokens. An `httpOnly` authentication cookie is now the only credential for a backoffice session. API users, Swagger, and Postman still authenticate with OpenID Connect and are unchanged.
Changes for backoffice extensions:
* The token methods on the auth context have been removed: `getLatestToken`, `validateToken`, `makeRefreshTokenRequest`, `completeAuthorizationRequest` and `clearTokenStorage`.
* Send requests with the browser cookie, using `credentials: 'include'` or `configureClient()`. Remove any `Authorization` header you set yourself.
* Use `getIsAuthorized()` or `session$` to check the session state, and `keepAlive()` to extend a session.
* The `umb-app-oauth` element (`UmbAppOauthElement`) has been removed.
* `UmbAuthProviderDefaultProps.onSubmit` no longer accepts a provider name. Pass the manifest instead.
For examples, see the [Fetch API](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/foundation/fetching-data/fetch-api.md) and [Umbraco HTTP Client](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/foundation/fetching-data/http-client.md) articles.
Changes for configuration and server-side code:
* `BackOfficeTokenCookieSettings` has been removed. Use the [`Umbraco:CMS:Security:AuthCookieName`](/umbraco-cms/19.latest/develop-with-umbraco/configuration/securitysettings.md#auth-cookie-name) setting to name the cookie.
* Preview now uses the backoffice cookie instead of a separate preview token.
* Viewing trashed media now uses the backoffice cookie. The `UMB_UCONTEXT_EXPOSED` cookie and its supporting classes have been removed.
See [#23484](https://github.com/umbraco/Umbraco-CMS/pull/23484), [#23698](https://github.com/umbraco/Umbraco-CMS/pull/23698) and [#23616](https://github.com/umbraco/Umbraco-CMS/pull/23616).
### Property editors split into single and multiple variants
Some property editors returned a different model type depending on their Data Type configuration. For example, changing "maximum number of items" from 1 to 2 changed the type that templates received. Each of these editors is now split in two, and the upgrade moves your Data Types to the matching editor.
| Was decided by | Existing editor keeps | New editor |
| ---------------------------- | -------------------------------------- | ----------------------------------------------------------------------------- |
| Value type | `Umbraco.Label` (string) | `Umbraco.Label.Text`, `.Integer`, `.BigInt`, `.Decimal`, `.DateTime`, `.Time` |
| Enable range | `Umbraco.Slider` (single value) | `Umbraco.Slider.Range` |
| Pick multiple items | `Umbraco.MediaPicker3` (multiple) | `Umbraco.MediaPicker.Single` |
| Maximum number of items is 1 | `Umbraco.MultiUrlPicker` (multiple) | `Umbraco.UrlPicker.Single` |
| Enable multiple choice | `Umbraco.DropDown.Flexible` (multiple) | `Umbraco.DropDown.Single` |
Stored property values and Delivery API output are unchanged. New Document and Member pickers are also available: `Umbraco.DocumentPicker.Multiple` and `Umbraco.MemberPicker.Multiple`.
Things to check after the upgrade:
* **Packages and deployment artifacts** that create Data Types or refer to the old editor aliases and configuration. See [Plan for deployment artifacts](#plan-for-deployment-artifacts).
* **Required properties**: Data Types moved to a single-item editor lose their item-count configuration. If a minimum of 1 made a property required, set the property to mandatory on the Document Type instead.
* **Multi URL Picker limits**: `maxNumber` no longer trims the value when it's read. A property holding more links than its limit now renders all of them.
* **Block List single block mode**: the obsolete `useSingleBlockMode` configuration is no longer read, and `Umbraco.BlockList` always returns a `BlockListModel`. The Umbraco 18 migration already moved these Data Types to the single block editor.
* **Code changes**: `MediaPicker3ConfigurationExtensions` is renamed to `MediaPickerConfigurationExtensions`. `Constants.PropertyEditors.Aliases.DropDownListFlexible` is renamed to `MultipleDropDown`, with an obsolete alias kept.
#### Multi Node Tree Picker deprecated
The Multi Node Tree Picker (`Umbraco.MultiNodeTreePicker`) is deprecated and is scheduled for removal in Umbraco 22 or 26 (to be confirmed). Existing properties that use it keep working. It's hidden when you choose a property editor for a new Data Type.
Use the dedicated [Document Picker](/umbraco-cms/19.latest/model-your-content/property-editors/built-in-umbraco-property-editors/document-picker.md), [Media Picker](/umbraco-cms/19.latest/model-your-content/property-editors/built-in-umbraco-property-editors/media-picker-3.md) and [Member Picker](/umbraco-cms/19.latest/model-your-content/property-editors/built-in-umbraco-property-editors/member-picker.md) instead. These now support dynamic roots, multiple items, and member type filters.
To show deprecated property editors in the backoffice, set `Umbraco:CMS:DataTypes:ShowDeprecatedPropertyEditors` to `true`. This setting has moved from the `Content` section. See [Data Types Settings](/umbraco-cms/19.latest/develop-with-umbraco/configuration/datatypes.md).
See [#23853](https://github.com/umbraco/Umbraco-CMS/pull/23853).
### Minimum and maximum configuration replaced by ranges
Property editors with separate minimum and maximum configuration fields now use a single range field. This prevents a minimum that's higher than the maximum. The upgrade migrates existing Data Types, and flags any with an invalid range for an editor to correct.
| Property editor | Old configuration keys | New configuration key |
| ----------------------- | --------------------------- | --------------------- |
| Numeric and Decimal | `min` / `max` | `validationRange` |
| Slider and Range Slider | `minVal` / `maxVal` | `validationRange` |
| Multiple Text String | `min` / `max` | `validationLimit` |
| Multi URL Picker | `minNumber` / `maxNumber` | `validationLimit` |
| Multi Node Tree Picker | `minNumber` / `maxNumber` | `validationLimit` |
| Block Grid areas | `minAllowed` / `maxAllowed` | `validationLimit` |
Update code that reads Data Type configuration by the old key names. The `ValidationLimit` property on some configuration classes now uses the shared `Umbraco.Cms.Core.PropertyEditors.NumberRange` type. This affects the Media Picker, Block List, Block Grid, Entity Data Picker, and Element Picker configuration classes. Recompile code that reads or writes it. See [#23470](https://github.com/umbraco/Umbraco-CMS/pull/23470).
### User group permission for editing shared content
On content that varies by culture, invariant (shared) properties are now controlled by a user group permission. Previously, access to the default language allowed editing them, or the `AllowEditInvariantFromNonDefault` setting allowed editing from any language. The setting has been removed.
The upgrade grants the new permission so that existing user groups keep the access they had:
* If `AllowEditInvariantFromNonDefault` was `true`, every user group gets the permission.
* Otherwise, Administrators and groups with access to all languages or the default language get the permission.
New user groups start without the permission. Review the **Allow editing shared content** option on your [User Groups](/umbraco-cms/19.latest/manage-and-publish-content/users-and-members/users.md#user-group-parameters) after the upgrade. The permission applies to both Documents and Elements. Language access now also applies to Elements in the Library section, not only to Documents.
Scheduled publishing follows the same rule. A schedule stores whether the user who created it had the permission. When the schedule runs, shared property changes are only published if that user had the permission.
Changes for developers:
* `CreateUserGroupRequestModel` and `UpdateUserGroupRequestModel` in the Management API require the new `hasAccessToInvariantForVariant` property. Requests without it are rejected with a `400 Bad Request`.
* Publishing now requires an existing user for access checks. Passing the ID of a user that doesn't exist, such as `Constants.Security.UnknownUserId`, throws an exception.
* `ICultureImpactFactory`, `CultureImpact`, `CultureImpactFactory`, `PublishableContentServiceBase` and `ContentEditingServiceBase` have changed signatures. The `isDefault` parameter on `ICultureImpactFactory.ImpactExplicit` keeps its type but now means `includeInvariantForVariant`.
* Overrides of `PublishableContentServiceBase.CommitContentChanges` must add the new `bool? includeInvariantForVariant` parameter.
* The `ContentSchedule` constructors and `ContentScheduleCollection.AddOrUpdate` take a new `bool? includeInvariantForVariant` parameter. `ContentSchedule.Equals` now compares it.
* In the backoffice client, `UMB_LANGUAGE_ACCESS_WORKSPACE_CONTEXT` and the `allowEditInvariantFromNonDefault` configuration property have been removed. Read `hasAccessToInvariantForVariant` on the current user instead.
* The `Umb.WorkspaceContext.Document.AllowEditInvariantFromNonDefault` and `Umb.WorkspaceContext.DocumentBlock.AllowEditInvariantFromNonDefault` manifests have been removed. Remove any references to these aliases.
* Custom implementations of the `UmbContentWorkspaceContext` interface must add `nameWriteGuard`, `isWritableVariant()` and `getIsWritableVariant()`. Classes extending `UmbContentDetailWorkspaceContextBase` already have them.
* `UmbCurrentUserModel` and `UmbUserGroupDetailModel` have a new required `hasAccessToInvariantForVariant` property.
See [#24022](https://github.com/umbraco/Umbraco-CMS/pull/24022) and [#24314](https://github.com/umbraco/Umbraco-CMS/pull/24314).
### Segment removed from content variant models
A segment has only ever been an override of property values within a language. You can't name, save, or publish a segment separately. However, some variant models had a `segment` property, which suggested otherwise. Umbraco 19 removes it so the models match how segments work. For an overview, see the [Variants](/umbraco-cms/19.latest/model-your-content/content-types-and-structure/backoffice/variants.md) article.
Changes for integrations and extensions:
* The Management API variant request and response models for Documents, Elements, Media, and Members no longer have a `segment` property. For example, this affects `DocumentVariantRequestModel` and `DocumentVariantResponseModel`.
* Property value models keep their `segment` property. Read and write segment content through the property values.
* On the server, the `Segment` property is removed from `VariantModel`, `VariantModelBase` and `BlockItemVariation`. `VariantModelBase` no longer implements `IHasCultureAndSegment`.
* Blocks are exposed per culture only, not per segment.
* The `SegmentSettings.AllowCreation` setting and the matching `allowNonExistingSegmentsCreation` property in the Management API have been removed.
* The backoffice client no longer includes `UmbDocumentSegmentRepository`. Segment options now come from workspace context extensions, so you can replace or add segment providers. See the `workspace-variant-segments` example in the Umbraco CMS repository.
* `variantOptions` and `languages` on `UmbContentDetailWorkspaceContextBase` can be `undefined` while loading.
* The `Cultures` property has been removed from the `Segment` model, the Management API segment response model, and `UmbSegmentModel` in the backoffice client. Segments can no longer be limited to specific cultures, so every segment is offered for every language.
* `ISegmentService.GetPagedSegmentsForDocumentAsync()` has been removed, along with the `/document/{id}/available-segment-options` Management API endpoint. These were temporary workarounds introduced in Umbraco 17.
Elements can now vary by segment, both in the Library and in block editors.
See [#23060](https://github.com/umbraco/Umbraco-CMS/pull/23060), [#24104](https://github.com/umbraco/Umbraco-CMS/pull/24104) and [#24222](https://github.com/umbraco/Umbraco-CMS/pull/24222).
### Reusable content in block editors
Blocks in the Block List, Block Grid, Single Block, and Rich Text editors can now reference a shared Element from the Library. For more information about Elements, see the [Elements](/umbraco-cms/19.latest/model-your-content/content-types-and-structure/data/defining-content/elements.md) article.
To support this, each block layout item now has its own `key`, separate from `contentKey`. Existing data without a key is handled when it's loaded. Code that builds block data directly must supply the key:
* `UmbBlockLayoutBaseModel` requires a `key` property.
* The Tiptap `setBlock()` and `setBlockInline()` commands require a `layoutKey` as well as the `contentKey`.
* Deletion methods on the block manager and entries contexts expect a layout key instead of a content key.
* Rich Text Editor markup carries a `data-key` attribute for each block. Markup without it keeps working.
`IPublishedElement` has a new `OwningContentId` property, which holds the ID of the content item that owns a block. Custom implementations of `IPublishedElement` should implement it. See [#22448](https://github.com/umbraco/Umbraco-CMS/pull/22448), [#23195](https://github.com/umbraco/Umbraco-CMS/pull/23195) and [#23753](https://github.com/umbraco/Umbraco-CMS/pull/23753).
### Document Blueprints moved to the Library section
Document Blueprints are now managed in the **Library** section instead of the **Settings** section. Access to them is configured per User Group and User, with a Document Blueprint start node. For more information, see the [Document Blueprints](/umbraco-cms/19.latest/model-your-content/content-types-and-structure/backoffice/document-blueprints.md) article.
During the upgrade, User Groups with access to the Settings section get access to the Library section and to all Document Blueprints. A group with the **Create Document Blueprint** permission but no Document Blueprint access loses the action until you grant a start node.
Document Blueprints can now only be created for Document Types that allow them. Element Types are excluded, and content type filters are applied.
Recommended actions:
* Review your User Groups after the upgrade, and grant access to any other group that needs it.
* Review custom code that works with Users, User Groups, Document Types, or Document Blueprints. `IUser`, `IUserGroup` and `IReadOnlyUserGroup` have new required members.
* Custom implementations of `IContentTypeService` must implement `GetAllAllowedForBlueprintsAsync`.
* Replace the removed Document Blueprint options modal with the create entity action and `entityCreateOptionAction` extensions.
See [#23906](https://github.com/umbraco/Umbraco-CMS/pull/23906) and [#23908](https://github.com/umbraco/Umbraco-CMS/pull/23908).
### Configuration changes
Some settings have moved, been removed, or have new default values. Review your `appsettings.json` files.
| Setting | Change | Action |
| ----------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Umbraco:CMS:Core:Debug` | No longer read. | Move the settings to [`Umbraco:CMS:Debug`](/umbraco-cms/19.latest/develop-with-umbraco/configuration/debugsettings.md). |
| `Umbraco:CMS:Content:ShowDeprecatedPropertyEditors` | No longer read. | Move it to [`Umbraco:CMS:DataTypes:ShowDeprecatedPropertyEditors`](/umbraco-cms/19.latest/develop-with-umbraco/configuration/datatypes.md). |
| `Umbraco:CMS:Content:AllowEditInvariantFromNonDefault` | Removed. | Use the user group permission. See [User group permission for editing shared content](#user-group-permission-for-editing-shared-content). |
| `Umbraco:CMS:HelpPage` | Removed. | Remove the section. |
| `AllowCreation` in the segment settings (`SegmentSettings`) | Removed. | Remove the setting. |
| `BackOfficeTokenCookieSettings` | Removed. | Use [`Umbraco:CMS:Security:AuthCookieName`](/umbraco-cms/19.latest/develop-with-umbraco/configuration/securitysettings.md#auth-cookie-name). |
| `Umbraco:CMS:Imaging:Memory:Enabled` | Defaults to `true`. | Set it to `false` to restore the previous behavior. See [Memory](/umbraco-cms/19.latest/develop-with-umbraco/configuration/imagingsettings.md#memory). |
| `Umbraco:CMS:ScheduledPublishing:AlignToClock` | Defaults to `true`. | Set it to `false` to restore the previous behavior. See [AlignToClock](/umbraco-cms/19.latest/develop-with-umbraco/configuration/scheduledpublishingsettings.md#aligntoclock). |
| `Umbraco:CMS:ModelsBuilder:ModelsMode` | Defaults to `Nothing`. | See the note below the table. |
| `Connect Timeout` in the connection string | No longer used as the command timeout. | Set `Command Timeout`. See [Set the database command timeout explicitly](#set-the-database-command-timeout-explicitly). |
The `ModelsMode` default changes from `InMemoryAuto` to `Nothing`, because core Umbraco can't generate in-memory models on its own. Sites with the `Umbraco.Cms.DevelopmentMode.Backoffice` package installed keep `InMemoryAuto` when no mode is set. Without the package, setting `InMemoryAuto` explicitly now stops the site at startup with a clear error. For more information, see [Models Builder settings](/umbraco-cms/19.latest/develop-with-umbraco/configuration/modelsbuildersettings.md).
In code, `CoreDebugSettings` is renamed to `DebugSettings`. Update any `IOptions` references. See [#24015](https://github.com/umbraco/Umbraco-CMS/pull/24015), [#23834](https://github.com/umbraco/Umbraco-CMS/pull/23834) and [#23756](https://github.com/umbraco/Umbraco-CMS/pull/23756).
### Management API and Delivery API changes
The following Management API endpoints have been removed:
* `GET /umbraco/management/api/v1/help`. There is no replacement.
* `GET /umbraco/management/api/v1/document/{id}/available-segment-options`. Use the segment collection endpoint instead. See [Segment removed from content variant models](#segment-removed-from-content-variant-models).
* `GET /umbraco/management/api/v1/server/upgrade-check`. There is no replacement.
* `POST /umbraco/management/api/v1/redirect-management/status`. Use the `Umbraco:CMS:WebRouting:DisableRedirectUrlTracking` setting instead. The endpoint had no effect from Umbraco 17.6 and 18.1.
The `AllowNonExistingSegmentsCreation` and `allowEditInvariantFromNonDefault` properties are removed from the Document and Element configuration response models. `DisableUnpublishWhenReferenced` is removed from the Media configuration response model.
In the Delivery API OpenAPI document, operation IDs use an underscore for the minor version. For example, `GetContent2.0` is now `GetContent2_0`. Regenerate any API clients built from the [Content Delivery API](/umbraco-cms/19.latest/develop-with-umbraco/headless-and-apis/content-delivery-api.md) document.
### Obsolete server-side code removed
Code marked as obsolete with removal scheduled for Umbraco 19 has been removed. In most cases, the obsolete warning in Umbraco 17 or 18 names the replacement. The main types of change are:
* **Constructors**: obsolete constructor overloads have been removed. Only the constructor taking all parameters remains. Classes that inherit from Umbraco base classes might need to pass extra constructor arguments.
* **Default interface implementations**: temporary default implementations on many interfaces have been removed. Custom implementations of these interfaces must now implement the members.
* **Synchronous methods**: remaining synchronous methods with async replacements have been removed.
Some notable removals and their replacements:
| Removed | Use instead |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PublishedContentBase` | `PublishableContentBase` |
| `IPublishStatusQueryService`, `IPublishStatusManagementService` | `IDocumentPublishStatusQueryService`, `IDocumentPublishStatusManagementService` |
| Synchronous `IAuditService` methods | The `…Async` methods and `IAuditEntryService` |
| `IMigrationPlanExecutor.ExecutePlan` | `ExecutePlanAsync` |
| `IRecurringBackgroundJob.RunJobAsync()` | `RunJobAsync(CancellationToken)` |
| `IEmailSender.CanSendRequiredEmail()` | `IsEmailConfigured()` or `IsEmailAvailableAsync()` |
| `IUserForgotPasswordSender.CanSend()` | `IsPasswordResetConfigured()` or `IsPasswordResetAvailableAsync()` |
| `HeyRedMarkdownToHtmlConverter` | `MarkdigMarkdownToHtmlConverter`. See [Markdown to HTML conversion](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/services/markdown-to-html-conversion.md). |
| Legacy log viewer types, such as `ILogViewerConfig` and `LogViewerConfig` | `ILogViewerService` |
| `MethodInfoApiCommonExtensions.HasMapToApiAttribute` | `ActionDescriptorApiCommonExtensions.HasMapToApiAttribute` |
| `DeliveryApiApplicationBuilderExtensions` | `UmbracoEndpointBuilderContextExtensions` |
| `IJsonPatchService`, install and upgrade check services | No replacement |
The `Markdown` (HeyRed) and `JsonPatch.Net` NuGet packages are no longer dependencies of Umbraco. Add a direct package reference if your own code uses them.
In migrations, `AddColumnIfNotExists()` is obsolete and every `AddColumn()` overload now returns a `bool`. `AddColumnIfNotExists()` now adds the column when the supplied column list has no entry for the table.
For the full lists, see [#24015](https://github.com/umbraco/Umbraco-CMS/pull/24015), [#24177](https://github.com/umbraco/Umbraco-CMS/pull/24177), [#24285](https://github.com/umbraco/Umbraco-CMS/pull/24285) and [#23984](https://github.com/umbraco/Umbraco-CMS/pull/23984).
### Backoffice client changes
Client-side APIs deprecated for removal in Umbraco 19 have been removed. These include:
* `tryExecuteAndNotify`. Use `tryExecute` instead. See [Executing Requests](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/foundation/fetching-data/try-execute.md).
* The `@umbraco-cms/backoffice/external/openid` package and the UUI 1.x compatibility exports.
* The document publish, unpublish, and rollback modals, and the templating create options modals.
* The `HealthCheck` interface, `UmbDefaultItemModel`, and deprecated tree, collection, and repository members.
Other changes that affect extensions:
* **Conditions** must set `permitted` themselves. A condition is now `undefined` until it resolves, instead of `false`. If your condition consumes a context, set `permitted` to `false` when the context isn't found. See [Condition](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/extending-overview/extension-types/condition.md).
* **Property editors** keep their element when you switch variant. The `supportsVariantChange` option has been removed. Make sure custom property editors update when their value changes.
* **The Partial View entry point** alias is now `Umb.EntryPoint.PartialView` instead of `Umb.EntryPoint.Partial View`.
See [#24189](https://github.com/umbraco/Umbraco-CMS/pull/24189), [#24222](https://github.com/umbraco/Umbraco-CMS/pull/24222) and [#23634](https://github.com/umbraco/Umbraco-CMS/pull/23634).
### ImageSharp 4
The default imaging package, `Umbraco.Cms.Imaging.ImageSharp`, now uses ImageSharp 4 instead of ImageSharp 3. The `Umbraco.Cms.Imaging.ImageSharp2` package remains available if you need to stay on ImageSharp 2. Review custom code that uses ImageSharp APIs directly against ImageSharp 4. See [Image processing](/umbraco-cms/19.latest/develop-with-umbraco/application-code/backend-and-custom-logic/image-processing.md) and [#23334](https://github.com/umbraco/Umbraco-CMS/pull/23334).
### Other changes
* **Property value converters**: default converters now declare which built-in converter they replace, using `DefaultPropertyValueConverterAttribute`. `JsonValueConverter` no longer excludes the Media Picker. If you replaced or removed a built-in converter, check that the expected converter is still used. See [Property Value Converters](/umbraco-cms/19.latest/extend-your-project/backoffice-extensions/property-editors/property-value-converters.md) and [#23849](https://github.com/umbraco/Umbraco-CMS/pull/23849).
* **Local development**: in new projects, `launchSettings.json` uses Kestrel as the default profile instead of IIS Express. See [#22427](https://github.com/umbraco/Umbraco-CMS/pull/22427).
* **Database**: the unused `userGroupDefaultPermissions` column is dropped from the user group table.
### Other breaking changes
The full details of breaking changes can be found from [this list of labelled pull requests](https://github.com/umbraco/Umbraco-CMS/pulls?q=is:pr+label:category/breaking+is:closed+label:release/19.0.0).
Umbraco 18
### Swashbuckle replaced with Microsoft.AspNetCore.OpenApi
Umbraco no longer uses Swashbuckle for OpenAPI documentation. It has been replaced with [Microsoft.AspNetCore.OpenApi](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/overview). If you have custom APIs with OpenAPI documentation, you will need to update your code.
You can still use Swashbuckle for your own OpenAPI documents if you prefer, but Umbraco no longer ships or configures it. You are responsible for installing the `Swashbuckle.AspNetCore` NuGet package and wiring it up yourself.
The main changes you will need to migrate:
* **Registering OpenAPI documents** — replace `IConfigureOptions` with `AddOpenApi()` (and `AddOpenApiDocumentToUi()` to show it in the Swagger UI dropdown). See [Adding your own OpenAPI documents](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#adding-your-own-openapi-documents). For backoffice APIs, the new `AddBackOfficeOpenApiDocument(name, configure)` builder wires up authentication and Umbraco's conventions in one call — see [Custom Backoffice API](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/custom-backoffice-api.md).
* **Backoffice security requirements** — replace `BackOfficeSecurityRequirementsOperationFilterBase` with the `AddBackofficeSecurityRequirements()` extension. See [Custom Backoffice API](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/custom-backoffice-api.md).
* **Schema ID handlers** — `ISchemaIdHandler` / `SchemaIdHandler` / `ISchemaIdSelector` / `SchemaIdSelector` have been removed. Use `CreateSchemaReferenceId` on `OpenApiOptions`. See [Schema IDs](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#schema-ids).
* **Operation ID handlers** — `IOperationIdHandler` / `OperationIdHandler` / `IOperationIdSelector` / `OperationIdSelector` have been removed. Use `IOpenApiOperationTransformer`. See [Operation IDs](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#operation-ids).
* **Sub-types handlers** — `ISubTypesHandler`, `ISubTypesSelector`, `SubTypesHandler`, and `SubTypesSelector` have been removed. Configure JSON polymorphism through `JsonSerializerOptions` instead.
* **Document inclusion selector** — `IDocumentInclusionSelector` and `DocumentInclusionSelector` have been removed. Each document now controls its own membership through `ShouldInclude`.
* **Enum schema filter** — `EnumSchemaFilter` has been removed. Enum serialization is now driven by the document's `JsonOptions`.
* **Delivery API member authentication** — `ConfigureUmbracoMemberAuthenticationDeliveryApiSwaggerGenOptions` has been removed. Use the `AddDeliveryApiOpenApiMemberAuthentication()` extension. See [Testing with Swagger](/umbraco-cms/19.latest/develop-with-umbraco/headless-and-apis/content-delivery-api/protected-content-in-the-delivery-api.md#testing-with-swagger).
* **Route and availability configuration** — `OpenApiRouteTemplatePipelineFilter` overrides are no longer supported. Use `PostConfigure` instead. See [Route and availability](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#route-and-availability).
* **Controlling which endpoints appear in your document** — `[MapToApi]` no longer auto-filters custom documents. Set `ShouldInclude` on each document. See [Controlling which endpoints appear in your document](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#controlling-which-endpoints-appear-in-your-document).
* **OpenAPI spec version** — generated documents now use OpenAPI 3.1 instead of 3.0. Regenerated client SDKs may differ — verify your generator supports OpenAPI 3.1.
* **Source generator compilation (class libraries)** — class library projects that register OpenAPI documents must add `$(InterceptorsNamespaces);Microsoft.AspNetCore.OpenApi.Generated` to their `.csproj`. Without it, the build fails with "error CS9137: The 'interceptors' feature is not enabled." See [Adding your own OpenAPI documents](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/api-versioning-and-openapi.md#adding-your-own-openapi-documents).
#### OpenAPI URL changes
The OpenAPI endpoints have been renamed from `swagger` to `openapi` to follow Microsoft's naming conventions:
| Old URL | New URL |
| ---------------------------------------------- | -------------------------------------- |
| `/umbraco/swagger` | `/umbraco/openapi` |
| `/umbraco/swagger/{documentName}/swagger.json` | `/umbraco/openapi/{documentName}.json` |
### UmbracoApiController and front-end API auto-routing removed
The `UmbracoApiController` base class — obsoleted in Umbraco 15 — has now been removed, along with the convention-based front-end API auto-routing pipeline that supported it. Custom APIs must be written as standard ASP.NET Core controllers using the `[ApiController]` and `[Route]` attributes.
Before:
```csharp
public class ProductsController : UmbracoApiController
{
public IActionResult GetAll() => Ok(new[] { "Table", "Chair" });
}
```
After:
```csharp
using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("/api/shop/products")]
public class ProductsController : Controller
{
[HttpGet]
public IActionResult GetAll() => Ok(new[] { "Table", "Chair" });
}
```
### `IPublishedContent.Parent` and `IPublishedContent.Children` removed
The `Parent` and `Children` navigation members on `IPublishedContent` — obsolete in earlier versions — have now been removed.
In Razor views and other code with access to the ambient Umbraco services, switch to the equivalent extension methods `Parent()` and `Children()`, defined in the `Umbraco.Extensions` namespace.
Before:
```csharp
var parent = Model.Parent;
foreach (var child in Model.Children)
{
// ...
}
```
After:
```csharp
var parent = Model.Parent();
foreach (var child in Model.Children())
{
// ...
}
```
The extension methods are designed for view-side use and rely on ambient Umbraco services that may not be set up outside a web request. In code that runs outside a request — for example, a background service — inject `IDocumentNavigationQueryService` (or `IMediaNavigationQueryService` for media) to obtain parent and child keys. Resolve those keys through `IPublishedContentCache` or `IPublishedContentQuery`.
### `GetAtRoot()` removed
The `GetAtRoot()` method — obsolete in earlier versions — has now been removed from `UmbracoHelper`, `IPublishedContentCache`, and `IUmbracoContext.Content`. The replacement depends on the use case:
* To enumerate all root nodes inside a web request, use `ContentAtRoot()` on `UmbracoHelper` or `IPublishedContentQuery`:
```csharp
IEnumerable roots = Umbraco.ContentAtRoot();
```
* To enumerate root nodes outside a web request, inject `IDocumentNavigationQueryService` (or `IMediaNavigationQueryService` for media) and use its `TryGetRootKeys(out IEnumerable rootKeys)` method to obtain the root keys, then resolve them via `IPublishedContentCache.GetById(key)`.
* To look up a specific node by its key or ID, use `IPublishedContentQuery.Content(id)` (or `UmbracoHelper.Content(id)`) directly.
### Content finder and URL provider renames
The earlier `ContentFinderByUrl` and `DefaultUrlProvider` classes — obsolete since their `New`-suffixed replacements were introduced — have now been removed, and the replacements have been renamed to drop the suffix:
* `ContentFinderByUrlNew` → `ContentFinderByUrl`
* `NewDefaultUrlProvider` → `DefaultUrlProvider`
### `ILocalizationService` removed
`ILocalizationService` — obsolete since Umbraco 12 — has now been removed. Its responsibilities have been split between two services:
* `ILanguageService` for language operations.
* `IDictionaryItemService` for dictionary item operations.
The new services expose an asynchronous API throughout, removing the sync-over-async patterns that existed on `ILocalizationService`.
Before:
```csharp
public class MyComponent
{
private readonly ILocalizationService _localizationService;
public MyComponent(ILocalizationService localizationService)
=> _localizationService = localizationService;
public IEnumerable GetLanguages()
=> _localizationService.GetAllLanguages();
}
```
After:
```csharp
public class MyComponent
{
private readonly ILanguageService _languageService;
public MyComponent(ILanguageService languageService)
=> _languageService = languageService;
public async Task> GetLanguagesAsync()
=> await _languageService.GetAllAsync();
}
```
For dictionary item operations such as `GetDictionaryItemByKey`, switch the injected service to `IDictionaryItemService` and use the corresponding async method.
### `IFileService` split into per-file-type services
`IFileService` — obsolete in earlier versions — has now been removed. Its functionality was previously moved into four dedicated services:
| Old (`IFileService`) | New |
| -------------------- | --------------------- |
| Templates | `ITemplateService` |
| Partial views | `IPartialViewService` |
| Stylesheets | `IStylesheetService` |
| Scripts | `IScriptService` |
### Service cleanups: obsolete sync method removals
Synchronous methods on the following services — obsolete in earlier versions in favor of async equivalents — have now been removed. Switch to the `…Async` overloads:
* `IContentTypeBaseService` and `IDomainService` ([#22629](https://github.com/umbraco/Umbraco-CMS/pull/22629))
* `IDataTypeService` ([#22634](https://github.com/umbraco/Umbraco-CMS/pull/22634))
* `IEmailSender`, `MediaPermissions`, and `MemberConfigurationResponseModel` ([#22642](https://github.com/umbraco/Umbraco-CMS/pull/22642))
* `IMemberGroupService` ([#22632](https://github.com/umbraco/Umbraco-CMS/pull/22632))
* `IMemberService.GetMembersByPropertyValue` ([#22678](https://github.com/umbraco/Umbraco-CMS/pull/22678))
### `IHostingEnvironment.ApplicationMainUrl` is now nullable
The `ApplicationMainUrl` property on `IHostingEnvironment` is now declared as `Uri?`. Add a null-check before using it. See [#22558](https://github.com/umbraco/Umbraco-CMS/pull/22558).
### `UmbracoHelper.GetDictionaryValue` nullability change
The return type of `GetDictionaryValue` has been changed from `string?` to `string`. This matches the actual runtime behavior — an empty string is returned when no dictionary item is found for the key. Callers can remove any defensive null checks against the return value. See [#21372](https://github.com/umbraco/Umbraco-CMS/pull/21372).
### MigrationBase removed — migrations must inherit AsyncMigrationBase
The synchronous `MigrationBase` class has been removed. It was obsoleted in Umbraco 16, when `AsyncMigrationBase` was introduced.
All bundled migrations between Umbraco 13 and 17 have also been deleted. Custom migrations must inherit `AsyncMigrationBase` and implement `MigrateAsync`.
The synchronous `PackageMigrationBase` has likewise been removed. Package migrations must inherit `AsyncPackageMigrationBase`.
Before:
```csharp
public class AddCommentsTable : MigrationBase
{
public AddCommentsTable(IMigrationContext context) : base(context)
{
}
protected override void Migrate()
{
if (TableExists("BlogComments") == false)
{
Create.Table().Do();
}
}
}
```
After:
```csharp
public class AddCommentsTable : AsyncMigrationBase
{
public AddCommentsTable(IMigrationContext context) : base(context)
{
}
protected override Task MigrateAsync()
{
if (TableExists("BlogComments") == false)
{
Create.Table().Do();
}
return Task.CompletedTask;
}
}
```
Custom migration plans must also be executed via `IMigrationPlanExecutor.ExecutePlanAsync()`.
### Master Template renamed to Layout Template
To match the terminology used elsewhere in the editor and templating engine, "Master Template" has been renamed to "Layout Template" throughout the codebase:
* `ITemplate` adds `IsLayoutTemplate` and `LayoutTemplateAlias` properties.
* Service parameters previously named `masterTemplateId` are now `layoutTemplateId`.
The old `MasterTemplate…` members are retained as `[Obsolete]` shims and will be removed in Umbraco 20.
### `HideBackOfficeLogo` content setting removed
The `HideBackOfficeLogo` option has been removed from `ContentSettings`. Remove any entries for it from `appsettings.json`.
### `EnableMediaRecycleBinProtection` now defaults to `true`
The `EnableMediaRecycleBinProtection` content setting — introduced in Umbraco 17 — now defaults to `true`. With protection enabled, media files moved to the recycle bin are renamed with a `.deleted` suffix (and renamed back on restore). A middleware component blocks unauthenticated access to recycle bin media URLs.
To restore the previous (unprotected) behavior, set `Umbraco:CMS:Content:EnableMediaRecycleBinProtection` to `false` in your configuration.
### Default markdown converter changed
`MarkdigMarkdownToHtmlConverter` is now the default registered implementation of `IMarkdownToHtmlConverter`, replacing the previous Hey Red Markdown-based default.
The Hey Red Markdown library is deprecated, and the corresponding implementation will be removed in Umbraco 19. To revert to the previous behavior for now, register `HeyRedMarkdownToHtmlConverter` explicitly in a composer.
### EF Core type names: `EfCore` renamed to `EFCore`
EF Core code constructs in `Umbraco.Cms.Persistence.EFCore` have been renamed to use the all-uppercase `EF` acronym. For example, `EfCoreScope` is now `EFCoreScope`, `IEfCoreScopeProvider` is now `IEFCoreScopeProvider`, and `EfCoreMigrationExecutor` is now `EFCoreMigrationExecutor`. Code that referenced these types directly must be updated to the new casing.
### Block list "single mode" Data Types moved to the single block editor
The upgrade moves Block List Data Types configured in "single mode" to the Single Block property editor. Only the Data Type changes. Stored property values stay in the Block List format, which the Single Block editor can read.
The Single Block and Block List editors are interchangeable, so you can switch a Data Type between them without losing data. See [#24144](https://github.com/umbraco/Umbraco-CMS/pull/24144).
### `ConfigureSecurityStampOptions` service registration removed
The `ConfigureSecurityStampOptions` options-configuration class is no longer registered by the framework. Host applications that copied `Program.cs` from earlier versions should remove any explicit `services.ConfigureOptions()` call.
### Updated dependencies
As is usual for a major upgrade, Umbraco's dependencies have been updated to their latest compatible versions.
`Markdig` was updated to a major version from 0.45.0 to 1.1.x. If you are using this library directly — for example, via `MarkdigMarkdownToHtmlConverter` — minor API differences may be encountered.
`Microsoft.CodeAnalysis.CSharp` was updated by a major version from 4.14.0 to 5.0.0. Projects that take a direct dependency on Roslyn for code analysis may need updates.
The Serilog hosting packages were updated by a major version from 9.0.0 to 10.0.0. This includes `Serilog.AspNetCore`, `Serilog.Extensions.Hosting`, and `Serilog.Settings.Configuration`. Sites with custom Serilog configuration should review the [Serilog release notes](https://github.com/serilog/serilog-aspnetcore/releases).
`Asp.Versioning.Mvc` was updated by a major version from 8.1.1 to 10.0.0. Custom code using these APIs should review the new major version for breaking changes.
### Other breaking changes
The full details of breaking changes can be found from [this list of labelled PRs](https://github.com/umbraco/Umbraco-CMS/pulls?q=is:pr+label:category/breaking+is:closed+label:release/18.0.0).
Umbraco 17
### System dates are updated to UTC
In earlier versions of Umbraco, system dates have been primarily persisted as server time without time zone information, with some stored as UTC. With Umbraco 17, system dates are now always stored in UTC.
To ensure that existing stored system dates align, a migration will run when upgrading to Umbraco 17.
The migration consists of:
* Determining the current time zone for the server.
* If a time zone is detected and it is not already UTC, database queries will update all system dates previously stored as server time to UTC.
There is configuration available to customize this migration.
Adding the following configuration setting will disable the migration from running.
```json
"Umbraco": {
"CMS": {
"SystemDateMigration": {
"Enabled": false
}
}
}
```
You can also explicitly define the time zone for your server. If this is provided as the standard English name of the time zone, it will be used over the detected one.
```json
"Umbraco": {
"CMS": {
"SystemDateMigration": {
"LocalServerTimeZone": "Eastern Standard Time"
}
}
}
```
Progress of the migration is written to the Umbraco log file.
For more details on this update see the following PRs: [#19705](https://github.com/umbraco/Umbraco-CMS/pull/19705), [#19798](https://github.com/umbraco/Umbraco-CMS/pull/19798), and [#20112](https://github.com/umbraco/Umbraco-CMS/pull/20112).
### InMemoryAuto models builder and Razor runtime compilation have moved into their own package
The `InMemoryAuto` models builder and the Umbraco feature that uses Razor runtime compilation (`Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation`) have been moved to a separate package: `Umbraco.Cms.DevelopmentMode.Backoffice`.
#### Why was this change made
[Razor runtime compilation is obsolete in .NET](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete) and prevents Hot Reload from working. Since `InMemoryAuto` depends on Razor runtime compilation, keeping it in the core would prevent Hot Reload from working.
By moving `InMemoryAuto` to its own package, Umbraco can enable Hot Reload by default for a better development experience.
#### When you need to reference `Umbraco.Cms.DevelopmentMode.Backoffice`
Add the package if any of the following apply:
1. You use the `InMemoryAuto` models builder:
* By explicitly selecting `InMemoryAuto`.
* By starting a new project with the default `--models-mode` (which is `InMemoryAuto`, adding the package automatically).
2. You rely on Razor runtime compilation to edit templates via the backoffice.
3. You use the RoslynCompiler class (you'll also need to update your namespace usings).
{% hint style="info" %}
The choice to include `Umbraco.Cms.DevelopmentMode.Backoffice` depends on how you work with models and templates. It is not based in the hosting environment, and using it enables Razor runtime compilation and disables Hot Reload.
{% endhint %}
#### When you do not need the package
You don’t need to reference it if you use Models Builder in a source-code mode, such as:
* `AppData`
* `SourceCodeAuto`
* `SourceCodeManual`
{% hint style="warning" %}
**Important!** These modes do not rely on Razor runtime compilation. However, ensure the following settings are removed from your `.csproj` file.
```xml
false
false
```
{% endhint %}
#### Additional notes
If you use the `ModelsMode` enum or its extension methods, use the string constants in `Constants.ModelsBuilder.ModelsModes` instead.
For more details on this update, see [PR #20187](https://github.com/umbraco/Umbraco-CMS/pull/20187).
### Date Picker Property Editor Kind
The existing date picker that returns a `DateTime` object has been updated to provide one with a `Kind` of `Unspecified`. Previously, it was `UTc`, but this was incorrect because Umbraco cannot determine the intended use of a particular date picker. This update makes that explicit.
For more details on this update see the following PR: [#19727](https://github.com/umbraco/Umbraco-CMS/pull/19727).
### Color Picker Property Editor
The color picker property editor used for the built-in approved color Data Type will now always make available a `PickedColor` object. Previously, this was only output when labels were configured on the Data Type. Without labels the previous behavior was to expose a `string`.
For more details on this update see the following PR: [#19430](https://github.com/umbraco/Umbraco-CMS/pull/19430).
### Segmented Content Fallback
The Template and Delivery API output for segmented properties will perform an explicit fallback to the default segment, if they do not have a value.
In earlier versions, if you created a segmented version of a document, you had to complete every property. This made segments an editorial burden unless the behavior was customized. With the new behavior, segmented content now only needs to have the properties that require a segmented value completed.
For more details on this update see the following PR: [#20309](https://github.com/umbraco/Umbraco-CMS/pull/20309).
### Removal of Extension Methods
Extension and public helper methods, unused in Umbraco and obsolete in previous versions, have been removed.
These are:
* `GetAssemblyFile`
* `ToSingleItemCollection`
* `GenerateDataTable`, `CreateTableData`, `AddRowData`, `ChildrenAsTable`, `ChildrenAsTable` all related to `DataTable`
* `RetryUntilSuccessOrTimeout`
* `RetryUntilSuccessOrMaxAttempts`
* `HasFlagAny`
* `Deconstruct`
* `AsEnumerable`, `ContainsKey` and `GetValue` extending `NameValueCollection`
* `DisposeIfDisposable`
* `SafeCast`
* `ToDictionary` on `object`
* `SanitizeThreadCulture`
For more details on this update see the following PR: [#17051](https://github.com/umbraco/Umbraco-CMS/pull/17051).
### Tiptap external extensions package
The import namespace `@umbraco-cms/backoffice/external/tiptap` has been removed, replaced with `@umbraco-cms/backoffice/tiptap`.
This means backoffice extension code must be updated from:
```typescript
import { Editor } from '@umbraco-cms/backoffice/external/tiptap';
```
To:
```typescript
import { Editor } from '@umbraco-cms/backoffice/tiptap';
```
For more details on this update see the following PR: [#20256](https://github.com/umbraco/Umbraco-CMS/pull/20256).
### Client-side user related entities
The following components have been moved from `user` to `current-user` and exported.
* `UmbCurrentUserAllowMfaActionCondition`
* `UmbCurrentUserConfigRepository`
* `UmbCurrentUserConfigStore`
* `UMB_CURRENT_USER_CONFIG_STORE_CONTEXT`
They should now be imported from `@umbraco-cms/backoffice/current-user`.
For more details on this update see the following PR: [#20125](https://github.com/umbraco/Umbraco-CMS/pull/20125).
### URL provider updates
URL providers are now responsible for generating content preview URLs. To achieve this, the `IUrlProvider` interface has been extended with the `GetPreviewUrlAsync()` method.
The `IUrlProvider` interface must also provide a unique system-wide `Alias`.
Lastly, the `UrlInfo` class has been revamped to support this setup.
For more details on this update see the following PR: [#20021](https://github.com/umbraco/Umbraco-CMS/pull/20021).
See also this announcement: [#27](https://github.com/umbraco/Announcements/issues/27).
### HTTPS is enabled by default
The default value of the `UseHttps` configuration in [Global Settings](/umbraco-cms/19.latest/develop-with-umbraco/configuration/globalsettings.md) has been changed from `false` to `true`.
If you *need* to run Umbraco without HTTPS, make sure to update `appsettings.json` accordingly.
### Authentication for the backoffice client
Following the draft [Request for Comments (RFC) from the Internet Engineering Task Force (IETF)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps), the backoffice client authentication has been changed to tighten security.
This change affects *only* the backoffice client authentication against the Management API. API user authentication against the Management API remains unaffected, as does the Delivery API.
This change *might* affect custom backoffice extensions that interact with the Management API. All fetch requests to the Management API must include credentials by declaring `credentials: 'include'`.
By default, backoffice extensions built using the HQ package starter template are not affected.
For more details on this update, see the following PRs: [#20779](https://github.com/umbraco/Umbraco-CMS/pull/20779) and [#20820](https://github.com/umbraco/Umbraco-CMS/pull/20820).
### Updated dependencies
As is usual for a major upgrade, Umbraco’s dependencies have been updated to their latest compatible versions.
NPoco was updated by a major version from 5.7.1 to 6.1.0. There were some changes to Umbraco code necessary after this update, so customer projects or packages that use NPoco directly may also require some changes.
Swashbuckle was updated to a new major version 10.0.1. If you are using this library to provide a Swagger document in your package or project, changes around namespaces, nullability, and types will be encountered.
The other specific dependency updates made for Umbraco 17 for server and client-side libraries can be found in these PRs:
* [#20385](https://github.com/umbraco/Umbraco-CMS/pull/20385)
* [#20184](https://github.com/umbraco/Umbraco-CMS/pull/20184)
* [#20925](https://github.com/umbraco/Umbraco-CMS/pull/20925)
### Sections
In `UmbSectionContext`, the `setManifest()` method has been replaced with a manifest. This is done to align with most other extension types. The `ManifestSection` interface has been modified to extend `ManifestElementAndApi` instead of `ManifestElement`. The `UmbSectionElement` that a section extends from now extends `UmbControllerHostElement` instead of `HTMLElement`.
For more details on these updates, see the following PRs: [#20305](https://github.com/umbraco/Umbraco-CMS/pull/20305)
### Other breaking changes
The full details of breaking changes can be found from [this list of labelled PRs](https://github.com/umbraco/Umbraco-CMS/pulls?q=is:pr+label:category/breaking+is:closed+label:release/17.0.0).
Umbraco 16
### TinyMCE is removed
In Umbraco 15, two property editors were available for a rich text editor: TinyMCE and TipTap.
With Umbraco 16, only TipTap is available as an option out of the box. TinyMCE's [change of license](https://github.com/tinymce/tinymce/issues/9453#issuecomment-2327646149) precludes us from shipping it with the MIT-licensed Umbraco CMS.
When upgrading to Umbraco 16, any data types using TinyMCE will be migrated to use TipTap.
To continue to use TinyMCE, a third-party package must be installed prior to the upgrade. This will disable the migration and allow you to continue with TinyMCE.
### Package migrations are asynchronous
Umbraco 16 adds support for asynchronous migrations and part of this work involved creating a new base class for package migrations. This leads to a source-compatible but binary-incompatible breaking change. In practice, this means that package code using migrations and calling base class helper methods such as `TableExists` can be recompiled without change. But if built against 15 and run on 16, a "method missing" exception will be thrown. For more details on the feature and the changes implemented, see the [PR](https://github.com/umbraco/Umbraco-CMS/pull/17057).
### Examine is now registered via a composer
[A new abstraction and implementation for search](https://github.com/umbraco/Umbraco.Cms.Search) is being worked on in an external package. To support this, a method has been implemented to disable the default Examine-based search in Umbraco. This has required moving the Examine component registration to a composer.
There is no effect on the default search experience in Umbraco, but it may affect search customizations. As Examine is now registered in a composer, any custom code registered the same way is not guaranteed to run after the core setup. You should ensure to use a `[ComposeAfter(typeof(Umbraco.Cms.Infrastructure.Examine.AddExamineComposer))]` attribute to make sure custom code runs after Umbraco's default setup of Examine.
Read more in the article on [custom indexing](/umbraco-cms/19.latest/develop-with-umbraco/application-code/examine/indexing.md) and see [PR #18988](https://github.com/umbraco/Umbraco-CMS/pull/18988) for reference.
### Updated dependencies
As is usual for a major upgrade, the dependencies Umbraco takes have been updated to their latest, compatible versions. This had little impact on the code of Umbraco itself, so we don't expect this to affect upgraded customer projects.
The specific dependency updates made for Umbraco 16 can be found in these PRs: for [server-side](https://github.com/umbraco/Umbraco-CMS/pull/19117) and [client-side](https://github.com/umbraco/Umbraco-CMS/pull/19121) libraries.
### Other breaking changes
Other than the above, breaking changes are minimal in Umbraco 16. On the server side, changes are limited to removing already obsolete constructors and methods.
Client-side there are a few things to look out for if you've built extensions to the backoffice:
* When consuming contexts, an `undefined` response will be resolved when the context can't be provided or the host is disconnected. See [PR 19113](https://github.com/umbraco/Umbraco-CMS/pull/19113) for more information.
* Similarly, consuming a context as a promise can result in a promise rejection and getting a context can result in an undefined response. See [PR 18611](https://github.com/umbraco/Umbraco-CMS/pull/18611) for more information.
* When making calls to retrieve data from the server, if you used either of Umbraco's helper methods `tryExecute` or `tryExecuteAndNotify`, then you need to adjust your code slightly. `tryExecuteAndNotify` is obsolete, and `tryExecute` takes the 'host' as the first argument. See [PR 18939](https://github.com/umbraco/Umbraco-CMS/pull/18939) for more information.
* The `urls` property is no longer populated on the document and media detail response models. This was removed to alleviate performance concerns. Dedicated repositories and management API endpoints exist for retrieving URLs for documents and media. See [PR #19030](https://github.com/umbraco/Umbraco-CMS/pull/19030) and [PR 19130](https://github.com/umbraco/Umbraco-CMS/pull/19130).
The full details of breaking changes can be found from [this list of labelled PRs](https://github.com/umbraco/Umbraco-CMS/pulls?q=is:pr+label:category/breaking+is:closed+label:release/16.0.0).
Umbraco 15
### Snapshots are removed
Snapshots have been removed, meaning any code using `IPublishedSnapshot`, and by extension `IPublishedSnapshotAccessor`, must be updated. Inject `IPublishedContentCache` or `IPublishedMediaCache` and use those directly instead.
### Modelsbuilder models needs to be rebuilt
Models generated by ModelsBuilder used the `IPublishedSnapshot` interface, which has been removed. This means that the models need to be rebuilt. The approach to this will differ depending on the mode chosen:
### InMemoryAuto
Remove the `umbraco\Data\TEMP\InMemoryAuto` folder to trigger a rebuild of the models.
### SourceCodeAuto and SourceCodeManual
Remove the old models located in the `\umbraco\models` folder by default. This will cause your views to no longer be able to build due to missing types. To get around this you can disable the precompiled view temporarily by adding the following to your `.csproj` file:
```xml
false
false
```
This will allow your site to start up, but you will still see an error page when loading a page.
1. Disregard the error.
2. Enter the backoffice.
3. Rebuild the models from the ModelsBuilder dashboard.
You can now re-enable precompiled views and rebuild your site.
If you have custom C# code that references the models this will also not build. You can either comment out your custom code temporarily until the models have been rebuilt or fix the models manually. To fix the models manually you need to find and replace `IPublishedSnapshotAccessor` with `IPublishedContentTypeCache`.
### Handling Precompressed Files
When upgrading from Umbraco 14 to 15, you might notice that `JavaScript` and `CSS` files are automatically precompressed, adding additional `.br` and `.gz` files. This behavior is introduced in ASP.NET Core version 9, where static files are fingerprinted and precompressed by default at build and publish time.
To disable this feature, set `false` in your project file. If you are using Umbraco's templates: `dotnet new umbraco`, this setting is already included.
In the project containing the `/umbraco` folder, set `false` in the `.csproj` file. This ensures the CMS can manage its own system files correctly. If you have separate Class Library projects for your custom frontend assets (CSS, JS), you may set this to `true` for performance benefits.
For more details, see the [ASP.NET Core Documentation](https://learn.microsoft.com/en-us/aspnet/core/migration/80-90?view=aspnetcore-9.0\&tabs=visual-studio#replace-usestaticfiles-with-mapstaticassets).
Umbraco 14
Read more about the release of Umbraco 14 in the [Blog Post](https://umbraco.com/blog/umbraco-14-release/).
Below you can find the list of breaking changes introduced in Umbraco 14 CMS.
* [**AngularJS removed: A new backoffice built with Web Components, Lit, and fueled by the Umbraco UI Library**](https://github.com/umbraco/Umbraco.CMS.Backoffice)
This is by far the most impactful update of Umbraco in years. We’ve fundamentally changed the way you extend Umbraco. If you are experienced in developing Web Components you can now use your preferred framework for this. If you are unsure how to proceed, you can implement it with TypeScript and the Lit library like we’ve done. In this case, start with this article on how to [customize the Backoffice](https://docs.umbraco.com/umbraco-cms/customizing/overview).
The new Backoffice (Bellissima) is entirely built on the Umbraco UI Library. This means that you might experience some of your components not being rendered on the page because the name has been changed. You should be able to find equivalents to what you were used to. For example, the `umb-button` is now called `uui-button`, and `umb-box` is now `uui-box`. When extending the Backoffice, we encourage you to use our [Umbraco UI Library](https://uui.umbraco.com/) to ensure the same look and feel in your extensions. The UI Library is Open Source and [hosted on GitHub](https://github.com/umbraco/Umbraco.UI), so feel free to contribute with new components or raise issues or discussions.
* **Icons are based on Lucide.**
Umbraco 13 and earlier used sets of icons ranging from custom SVGs to Font Awesome. This has all been converged into the [Lucide icon pack](https://docs.umbraco.com/umbraco-cms/customizing/icons) with icon names mapped from Umbraco 13.
* **Custom icons**
To add custom icons to the Backoffice, you must add an extension type called “icons”, which can provide icons given a Name and a File. The file can reside anywhere on disk or in RCLs the only requirements being that it must be routable and it must be an SVG.
* **User provided translations**
Translations used in the UI (which are most of them) have been migrated from XML to JavaScript modules. This means that if you wish to override any of the built-in translation keys for the UI, you have to add an extension type called “localization”. It is still possible to add XML translations, but they can no longer be used in the Backoffice UI. However, you may still find usage for them in server-to-server scenarios. Umbraco also keeps its e-mail templates as XML translations. Package and extension developers working with localization will find many benefits from this change seeing that you can add logic to JavaScript modules making your localization files more dynamic and even making them able to react to input parameters.
You can read more about [localization on the Umbraco Documentation](https://docs.umbraco.com/umbraco-cms/extending/language-files).
* **BackOffice controllers have been replaced with the Management API**
Following the implementation of the new Backoffice (Bellissima), Umbraco has now internally upgraded Headless to a first-class citizen. This means that all controllers previously available under the `/umbraco/api` route have been removed and replaced with controllers in the Management API. You can read more about the Management API on the [Management API](https://docs.umbraco.com/umbraco-cms/reference/management-api) article. You can also check out the Swagger UI in your local Umbraco instance available under `/umbraco/swagger`.
* **A new way of writing authorized controllers**
If you have implemented API controllers in Umbraco before, we recommend you update or rewrite these. Follow the [Documenting your Controllers](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-backoffice-api/documenting-your-controllers) article, as you’ll then ensure the same cool documentation of your APIs. Notice, that we’ve made a much better separation of concern between controllers and services so that there is no more business logic in controllers.
* [**Migration from Newtonsoft.Json to the System.Text.Json which removes Nested Content and Grid value converter and so on**](https://github.com/umbraco/Umbraco-CMS/pull/15728)
Although this sounds like it's not a big change, it’s one of the most breaking changes on the backend. Whereas Newtonsoft.Json was flexible and error-tolerant by default, System.Text.Json is strict but more secure by default. You can therefore run into things that will not be serialized. You can [read more about the differences between Newtonsoft.Json and System.Text.Json here](https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/migrate-from-newtonsoft?pivots=dotnet-9-0).
* **Nested Content and Grid Layout have been removed**
These two property editors have been deprecated in Umbraco for some time as you can read in our breaking change announcements for [Nested Content](https://github.com/umbraco/Announcements/issues/6) and [Grid Layout](https://github.com/umbraco/Announcements/issues/7). The recommended action is to use blocks instead - Block Grid for the grid layout and either Block Grid or Block List for Nested Content.
* [**The legacy media picker has been removed**](https://github.com/umbraco/Umbraco-CMS/pull/15835)
We have for some time [encouraged to not use the legacy Media Picker](https://github.com/umbraco/Announcements/issues/8), and now it’s fully removed. You should use the default Media Picker instead.
* **Macros and Partial View Macros have been removed. Use partial views and/or blocks in the Rich Text Editor (RTE)**
Depending on the usage of macros, you’ll be able to use either partial views or blocks in the Rich Text Editor. They are not the same kind of functionality, but they cover all the identified use cases in a more consistent and supportable way.
For more information on migrating from macros to using blocks in the Rich Text Editor, see the [Migrating Macros](https://docs.umbraco.com/umbraco-cms/17.latest/get-started/upgrading-and-migrating/version-specific/migrating-macros) article.
* **XPath has been removed**
An alternative is using the Dynamic Roots in the Multinode Treepicker and for ContentXPath the alternative is [IContentLastChanceFinder](https://docs.umbraco.com/umbraco-cms/tutorials/custom-error-page).
* [**The package manifest format has changed**](https://docs.umbraco.com/umbraco-cms/customizing/umbraco-package)
The `package.manifest` file is no longer supported and has been replaced with the `umbraco-package.json` file. The format is similar and after building your Umbraco solution, you have access to a JSON schema file which you can reference and thereby have type-safety in the file. You can read more about the new format on the [Package Manifest](https://docs.umbraco.com/umbraco-cms/customizing/umbraco-package) article.
* **Smidge is no longer a default dependency**
[Smidge has been removed from the default installation](https://github.com/umbraco/Umbraco-CMS/pull/15788) along with the RuntimeMinification setting and related classes. Smidge used to bundle up Backoffice and package assets before, however, with the Bellissima, we have migrated entirely to ESModules. This means we can no longer predict how modules work in automated bundles.
It's recommended that you bundle up your Backoffice static assets for instance by a tool called Vite. You can read more about this on the [Vite Package Setup](https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup) article. You can still use libraries like Smidge for frontend static assets by manually installing the package from NuGet.
You can read the [Smidge documentation](https://github.com/Shazwazza/Smidge/wiki) on how to set up a similar setting to RuntimeMinification. For sites being upgraded from V13 or below, remove [these two lines](https://github.com/umbraco/Umbraco-CMS/blob/04ed514a21279ae82d95b34c55cb2ba96545eb39/src/Umbraco.Web.UI/Views/_ViewImports.cshtml#L7-L8) from the `_ViewImports.cshtml` file.
* **Base classes for Backoffice controllers have been removed**
The `UmbracoAuthorizedApiController` and `UmbracoAuthorizedJsonController` classes have been removed. We recommend basing your Backoffice APIs on the `ManagementApiControllerBase` class from the `Umbraco.Cms.Api.Management` project.
Read the [Creating a Backoffice API article](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-backoffice-api) for a comprehensive guide to writing APIs for the Management API.
* **Removal of certain AppSettings**
Some AppSettings have been removed or found a new place. In general, any UI-related app settings will now have to be configured as [extensions through the manifest system](https://docs.umbraco.com/umbraco-cms/customizing/extending-overview/extension-types).
* **RichTextEditor**
The global configuration of TinyMCE has been removed in order to support more rich text editors in the future. Instead, a new extension type called “tinyMcePlugin” has been added. This extension type gives you access to each instance of TinyMCE allowing you to configure it exactly as you see fit. You can even make it dependent on more factors such as Document Type, user group, environment, and much more. You have access to the full array of contexts in the Backoffice.
* **ShowDeprecatedPropertyEditors**
There are no deprecated property editors in Bellissima and this configuration will no longer have an effect.
* **HideBackOfficeLogo**
This configuration will no longer have an effect. Instead, you can add a CSS file where you can modify the default CSS variables in the Backoffice. The Backoffice loads a CSS file which can be overwritten by placing a similar file in your project at `/umbraco/backoffice/css/user-defined.css` with the following content:
```css
:root {
--umb-header-logo-display: none;
}
```
* **IconsPath**
This configuration will no longer have an effect. Instead, you should add icons through the “icons” extension type.
* **AllowedMediaHosts**
This configuration will no longer have an effect.
* **Notifications**
Notifications have changed their behavior to an extent. You can still implement notifications such as `ContentSavingNotification` to react to changes for related systems or add messages to be shown in the Backoffice. You can no longer modify the models being transferred through the API.
If you wish to modify the Backoffice UI, register the extensions through the manifest system that hook on to the desired areas of the Backoffice UI. If you used to modify the models because you needed more data on the models, it's recommended that you build your own API controller to achieve this. You can read more about [building custom API controllers on the Umbraco Documentation](/umbraco-cms/19.latest/extend-your-project/server-side-extensions/custom-backoffice-api.md) and even learn how to register your controllers in Swagger UI.
* **Property editors have been split in two**
The new Backoffice and the Management API ushers in a shift in responsibility. Traditionally, a lot of UI responsibility has been misplaced on the server.
For example, it is hardly a server concern how many rows a text area should span by default.
To this end, property editors have been split into two, individually reusable parts; the server implementation and the client implementation.
This change will likely impact custom Property Editors. See the [Migrate custom Property Editors to Umbraco version 14 and later](/umbraco-cms/19.latest/get-started/upgrading-and-migrating/find-your-upgrade-path/migrate-custom-property-editors-to-umbraco-14.md) article for details.
* **Property value converters for package.manifest based property editors**
The `package.manifest` file format is no longer known on the server side. It has been changed to be a purely client-side responsibility (and it has adopted a new format and a new name). If you have implemented a property value converter for a property editor defined in a `package.manifest` file, you will likely need to make a small change to the property value converter.
The property value converter must implement `IsConverter()` to determine if it can handle a given property. In this implementation, it is common to use the EditorAlias of the passed in IPublishedPropertyType. However, in Umbraco 14 you should use the EditorUiAlias instead.
More details can be found in [this article](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor/custom-value-conversion-for-rendering).
* **UmbracoApiController breakage**
Due to the shift from `Newtonsoft.Json` to the `System.Text.Json`, the `UmbracoApiController` will yield camel-cased output in Umbraco 14, where it was pascal-cased in the previous versions.
Make sure to perform thorough testing of all usages of `UmbracoApiController`. As the class has now been marked as obsolete, we recommend these controllers to be based on the Controller class from ASP.NET Core moving forward.
* **Two-Factor Authentication requires a client registration**
The C# models for Two-Factor Authentication previously supported setting a custom AngularJS view to setup the QR code. This has been moved to the Backoffice client and requires a registration through the new extension type [`mfaLoginProvider`](https://docs.umbraco.com/umbraco-cms/customizing/umbraco-package#extensions):
```typescript
{
"type": "mfaLoginProvider",
"alias": "my.2fa.provider",
"name": "My 2fa Provider",
"forProviderName": "UmbracoUserAppAuthenticator",
"meta": {
"label": "Authenticate with a 2FA code"
}
}
```
This will use Umbraco’s default configuration of the two-factor provider. The user scans a QR code using an app such as Google Authenticator or Authy by Twilio.
It is additionally possible to register your own configurator similar to Umbraco 13. You can achieve this by providing a custom JavaScript element through the `elementJs` property.
More details and code examples can be found in the [Two-Factor Authentication](/umbraco-cms/19.latest/run-in-production/security/two-factor-authentication.md) article.
* **External Login Providers require a client registration**
The C# models for External Login Providers have changed and no longer hold configuration options for the “Sign in with XYZ” button. To show a button in the Backoffice to sign in with an external provider, you need to register this through the extension type called [`authProvider`](https://docs.umbraco.com/umbraco-cms/customizing/umbraco-package#extensions) :
```typescript
{
"type": "authProvider",
"alias": "My.AuthProvider.Google",
"name": "Google Auth Provider",
"forProviderName": "Umbraco.Google",
"meta": {
"label": "Google",
"defaultView": {
"icon": "icon-google"
},
"linking": {
"allowManualLinking": true
}
}
}
```
This will use Umbraco’s default button to sign in with the provider. You can also choose to provide your own element to show in the login form. You can achieve this by adding the `elementJs` property.
Additionally, on the backend side, there is an additional helper available to do proper error handling. You can utilize this by using the options pattern to configure the provider.
More details and code examples can be found in the [External Login Providers](/umbraco-cms/19.latest/run-in-production/security/external-login-providers.md) article.
* **Deprecated SQLite provider name removed**
In previous versions of Umbraco the `umbracoDbDSN_ProviderName` (and `umbracoCommerceDbDSN_ProviderName`) value could be `Microsoft.Data.SQLite` or `Microsoft.Data.Sqlite` with the former being deprecated in Umbraco 12.
The deprecated version, `Microsoft.Data.SQlite`, has been removed and will require the value to be updated to `Microsoft.Data.Sqlite` for installations using an SQLite database.
```json
{
...
"ConnectionStrings": {
"umbracoDbDSN": "Data Source=|DataDirectory|/Umbraco.sqlite.db;Foreign Keys=True;Pooling=True",
"umbracoDbDSN_ProviderName": "Microsoft.Data.Sqlite",
"umbracoCommerceDbDSN": "Data Source=|DataDirectory|/Umbraco.Commerce.sqlite.db;Mode=ReadWrite;Foreign Keys=True;Pooling=True",
"umbracoCommerceDbDSN_ProviderName": "Microsoft.Data.Sqlite"
},
...
}
```
* **Webhook payload property casing has changed**
Following changes to serialization, property names in the payload now use camelCase instead of PascalCase. For example, the 'CreateDate' property is now 'createDate'.
**In-depth and further breaking changes for Umbraco 14 can be found on the** [**CMS GitHub**](https://github.com/umbraco/Umbraco-CMS/pulls?q=is%3Apr+base%3Av14%2Fdev+label%3Acategory%2Fbreaking) **repository and on** [**Our Website**](https://our.umbraco.com/download/releases/1400)**.**
Umbraco 14 RC Versions
Below you can find the list of breaking changes introduced in Umbraco 14 RC release versions.
### RC 5
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-rc5)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-rc5)
### RC 4
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-rc4)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-rc4)
### RC 3
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-rc3)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-rc3)
### RC 2
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-rc2)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-rc2)
### RC 1
First RC release - 17th of April. Breaking changes since Beta 3:
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-rc1)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-rc1)
Umbraco 14 Beta Versions
Below you can find the list of breaking changes introduced in Umbraco 14 Beta release versions.
### Beta 3
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-beta003)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-beta003)
### 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.
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-beta002)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-beta002)
### Beta 1
Official release of Beta, 6th March 2023.
* [Bellissima (frontend/backoffice) changes](https://github.com/umbraco/Umbraco.CMS.Backoffice/releases/tag/v14.0.0-beta001)
* [Backend (CMS) changes](https://github.com/umbraco/Umbraco-CMS/releases/tag/release-14.0.0-beta001)
Umbraco 13
Below you can find the list of breaking changes introduced in Umbraco 13.
* [Use ISO codes instead of language IDs for fallback languages and translations](https://github.com/umbraco/Umbraco-CMS/issues/13751)
* [Breaking changes for the Delivery API](https://github.com/umbraco/Umbraco-CMS/issues/14745)
* [V13: New login screen](https://github.com/umbraco/Umbraco-CMS/issues/14780)
* [Updated NuGet Dependencies](https://github.com/umbraco/Umbraco-CMS/issues/14795)
* [Fix \`JsonNetSerializer\` settings leaking into derived implementations](https://github.com/umbraco/Umbraco-CMS/issues/14814)
* [Add default property value converters for all value types](https://github.com/umbraco/Umbraco-CMS/issues/14869)
* [V13: Add config to limit concurrent logins](https://github.com/umbraco/Umbraco-CMS/issues/14989)
* [Updates and support for re-use of CMS logic in Deploy](https://github.com/umbraco/Umbraco-CMS/issues/14990)
* [Don't explicitly index nested property by default](https://github.com/umbraco/Umbraco-CMS/issues/15028)
* [Blocks in the Rich Text Editor](https://github.com/umbraco/Umbraco-CMS/issues/15029)
* [Fix FurthestAncestorOrSelfDynamicRootQueryStep and FurthestDescendantOrSelfDynamicRootQueryStep](https://github.com/umbraco/Umbraco-CMS/issues/15113)
* [Remove parameter value/return nullability in \`IImageSourceParser\`, \`ILocalLinkParser\` and \`IMacroParser\`](https://github.com/umbraco/Umbraco-CMS/issues/15130)
* [Update PackageMigrationsPlans collection to be Weighted and not Lazy](https://github.com/umbraco/Umbraco-CMS/issues/15138)
* [Move IContextCache parameter to base Deploy interfaces and add checksum to artifact dependency](https://github.com/umbraco/Umbraco-CMS/issues/15144)
* [V13: Update IWebHookService to proper casing](https://github.com/umbraco/Umbraco-CMS/issues/15169)
* [V13: Implement webhook as i entity](https://github.com/umbraco/Umbraco-CMS/issues/15267)
* [Change \`WebhookEventCollectionBuilder\` to set collection](https://github.com/umbraco/Umbraco-CMS/issues/15351)
* [V13: Log webhook firing exceptions when they happen](https://github.com/umbraco/Umbraco-CMS/issues/15393)
* [Remove date header from webhook request and use constants](https://github.com/umbraco/Umbraco-CMS/issues/15407)
You can find more information about all breaking changes for v13.0.0 on [Our Umbraco](https://our.umbraco.com/download/releases/1300) website.
{% hint style="info" %}
You need to be aware of some things if you are using EF Core, and have installed the `Microsoft.EntityFrameworkCore.Design 8.0.0` package:
* This package has a transient dependency to `Microsoft.CodeAnalysis.Common` which clashes with the same transient dependency from `Umbraco.Cms 13.0.0`. This happens because `Microsoft.EntityFrameworkCore.Design 8.0.0` requires `Microsoft.CodeAnalysis.CSharp.Workspaces` in v4.5.0 or higher.
* If there are no other dependencies that need that package then it installs it in the lowest allowed version (4.5.0). That package then has a strict dependency on `Microsoft.CodeAnalysis.Common` version 4.5.0. The problem is `Umbraco.Cms` through its own transient dependencies that require the version of `Microsoft.CodeAnalysis.Common` to be >= 4.8.0.
* This can be fixed by installing `Microsoft.CodeAnalysis.CSharp.Workspaces` version 4.8.0 as a specific package instead of leaving it as a transient dependency. This is because it will then have a strict transient dependency on `Microsoft.CodeAnalysis.Common` version 4.8.0, which is the same that Umbraco has.
{% endhint %}
{% hint style="success" icon="lightbulb-message" %}
Community Insight: Watch this [video walkthrough](https://www.youtube.com/watch?v=LHW3bbIR_VU) for a deep dive into the major changes from Umbraco 13 through 17.
{% endhint %}
Umbraco 12
Umbraco 12 does not include many binary breaking changes, but there are some.
Most notable is a functional breaking change in Migrations, that from Umbraco 12. Each translation will be executed in its own transactions instead of all migrations in one big transaction. This change has been made to ease the support for Sqlite.
### A type, enum, record, or struct visible outside the assembly is missing in the compared assembly when required to be present
* PagedModel has moved namespace from Umbraco.New\.Cms.Core.Models to Umbraco.Cms.Core.Models
* Umbraco.Cms.Infrastructure.Migrations.PostMigrations.ClearCsrfCookies is removed. The functionality can be archived by implementing a notification handler for the new UmbracoPlanExecutedNotification.
* Umbraco.Cms.Core.Cache.DistributedCacheBinder is now divided into separate files for each notification handler
* Umbraco.Cms.Infrastructure.Migrations.PostMigrations.DeleteLogViewerQueryFile was a no-op method removed.
* Umbraco.Cms.Infrastructure.Migrations.PostMigrations.RebuildPublishedSnapshot replaced with a RebuildCache flag on the MigrationBase
### A member that is visible outside of the assembly is missing in the compared assembly when required to be present
* Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.Execute(Umbraco.Cms.Infrastructure.Migrations.MigrationPlan,System.String) replaced with Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.ExecutePlan(Umbraco.Cms.Infrastructure.\* \* Migrations.MigrationPlan,System.String) that returns an rich object instead of a string
* Umbraco.Cms.Infrastructure.Migrations.IMigrationContext.AddPostMigration\`\`1 Removed and replaced with notification
* Umbraco.Cms.Infrastructure.Migrations.MigrationPlan.AddPostMigration\`\`1
* Removed and replaced with notification
* Umbraco.Cms.Infrastructure.Migrations.MigrationPlan.get\_PostMigrationTypes removed.
* Umbraco.Cms.Infrastructure.Migrations.Upgrade.Upgrader.Execute(Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor,Umbraco.Cms.Core.Scoping.IScopeProvider,Umbraco.Cms.Core.Services.IKeyValueService) was obsolete and is replaced by method taking a ICoreScopeProvider instead of a IScopeProvider
### An abstract member was added to the right side of the comparison to an unsealed type
* PublishedPropertyBase now requires inheritors to implement GetDeliveryApiValue(System.Boolean,System.String,System.String)
### A member was added to an interface without a default implementation
* Umbraco.Cms.Core.Events.IEventAggregator.Publish`2(System.Collections.Generic.IEnumerable{`0})
* Umbraco.Cms.Core.Events.IEventAggregator.PublishAsync`2(System.Collections.Generic.IEnumerable{`0},System.Threading.CancellationToken)
* Umbraco.Cms.Core.Models.PublishedContent.IPublishedProperty.GetDeliveryApiValue(System.Boolean,System.String,System.String)
* Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.ConvertInterToDeliveryApiObject(Umbraco.Cms.Core.Models.PublishedContent.IPublishedElement,Umbraco.Cms.Core.PropertyEditors.PropertyCacheLevel,System.Object,System.Boolean,System.Boolean)
* Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.ConvertInterToDeliveryApiObject(Umbraco.Cms.Core.Models.PublishedContent.IPublishedElement,Umbraco.Cms.Core.PropertyEditors.PropertyCacheLevel,System.Object,System.Boolean)
* Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType.DeliveryApiCacheLevel
* Umbraco.Cms.Core.Scoping.ICoreScope.Locks
* Umbraco.Cms.Core.Migrations.IMigrationPlanExecutor.ExecutePlan(Umbraco.Cms.Infrastructure.Migrations.MigrationPlan,System.String)
* Umbraco.Cms.Infrastructure.Search.IUmbracoIndexingHandler.RemoveProtectedContent
* Umbraco.Cms.Infrastructure.Examine.IUmbracoIndex.SupportProtectedContent
Umbraco 11
Most breaking changes are introduced due to **updated dependencies**. The breaking changes in .NET 7 and ASP.NET Core 7 are documented by [Microsoft](https://learn.microsoft.com/en-us/dotnet/core/compatibility/7.0).
Besides the documented changes, we have also seen a few method signatures that are changed to support Nullable-Reference-Types.
If you are using **TinyMCE** plugins or custom TinyMCE configuration you need to migrate to the latest version. Learn more about this in the [Rich Text Editor documentation](/umbraco-cms/19.latest/model-your-content/property-editors/built-in-umbraco-property-editors/rich-text-editor.md).
The breaking changes in TinyMCE are also documented in the official migration guides for [version 4 to 5](https://www.tiny.cloud/docs/migration-from-4x/) and from [version 5 to 6](https://www.tiny.cloud/docs/tinymce/6/migration-from-5x/).
The breaking changes in Umbraco 11 are mainly the removal of classes, methods, and so on, marked as obsolete in Umbraco 9.
A few methods and classes have also been moved and changed namespace. Decoupled dependencies are documented on the [Umbraco Announcements repository](https://github.com/umbraco/Announcements/issues/5).
The full list of API-breaking changes can be found below.
### Obsolete code removed
The following have been removed after having been obsoleted since Umbraco 9.
#### Umbraco.Extensions
```csharp
Umbraco.Extensions.ServiceCollectionExtensions.AddUnique(Microsoft.Extensions.DependencyInjection.IServiceCollection)
Umbraco.Extensions.EnumExtensions.HasFlagAll(T, T)
Umbraco.Extensions.FriendlyImageCropperTemplateExtensions.GetLocalCropUrl(Umbraco.Cms.Core.Models.MediaWithCrops, string, string?)
```
#### Umbraco.Cms.Core
```csharp
Umbraco.Cms.Core.Constants.Conventions.Member.IsApproved
Umbraco.Cms.Core.Constants.Conventions.Member.IsApprovedLabel
Umbraco.Cms.Core.Constants.Conventions.Member.IsLockedOut
Umbraco.Cms.Core.Constants.Conventions.Member.IsLockedOutLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastLoginDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastLoginDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastPasswordChangeDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastPasswordChangeDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.LastLockoutDate
Umbraco.Cms.Core.Constants.Conventions.Member.LastLockoutDateLabel
Umbraco.Cms.Core.Constants.Conventions.Member.FailedPasswordAttempts
Umbraco.Cms.Core.Constants.Conventions.Member.FailedPasswordAttemptsLabel
Umbraco.Cms.Core.WebAssets.IRuntimeMinifier.Reset()
Umbraco.Cms.Core.Services.IExternalLoginService
Umbraco.Cms.Core.Services.ExternalLoginService.ExternalLoginService(
Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
Microsoft.Extensions.Logging.ILoggerFactory,
Umbraco.Cms.Core.Events.IEventMessagesFactory,
Umbraco.Cms.Core.Persistence.Repositories.IExternalLoginRepository)
Umbraco.Cms.Core.Services.ExternalLoginService.GetExternalLogins(int)
Umbraco.Cms.Core.Services.ExternalLoginService.GetExternalLoginTokens(int)
Umbraco.Cms.Core.Services.ExternalLoginService.Save(int,
System.Collections.Generic.IEnumerable)
Umbraco.Cms.Core.Services.ExternalLoginService.Save(int,
System.Collections.Generic.IEnumerable)
Umbraco.Cms.Core.Services.ExternalLoginService.DeleteUserLogins(int)
Umbraco.Cms.Core.Services.IMacroWithAliasService
Umbraco.Cms.Core.Services.ITwoFactorLoginService2
Umbraco.Cms.Core.Services.LocalizedTextService.LocalizedTextService(
System.Collections.Generic.IDictionary>>,
Microsoft.Extensions.Logging.ILogger)
Umbraco.Cms.Core.Services.ServiceContext.ServiceContext(
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?,
System.Lazy?)
Umbraco.Cms.Core.Services.ServiceContext.CreatePartial(
Umbraco.Cms.Core.Services.IContentService?,
Umbraco.Cms.Core.Services.IMediaService?,
Umbraco.Cms.Core.Services.IContentTypeService?,
Umbraco.Cms.Core.Services.IMediaTypeService?,
Umbraco.Cms.Core.Services.IDataTypeService?,
Umbraco.Cms.Core.Services.IFileService?,
Umbraco.Cms.Core.Services.ILocalizationService?,
Umbraco.Cms.Core.Services.IPackagingService?,
Umbraco.Cms.Core.Services.IEntityService?,
Umbraco.Cms.Core.Services.IRelationService?,
Umbraco.Cms.Core.Services.IMemberGroupService?,
Umbraco.Cms.Core.Services.IMemberTypeService?,
Umbraco.Cms.Core.Services.IMemberService?,
Umbraco.Cms.Core.Services.IUserService?,
Umbraco.Cms.Core.Services.ITagService?,
Umbraco.Cms.Core.Services.INotificationService?,
Umbraco.Cms.Core.Services.ILocalizedTextService?,
Umbraco.Cms.Core.Services.IAuditService?,
Umbraco.Cms.Core.Services.IDomainService?,
Umbraco.Cms.Core.Services.IMacroService?,
Umbraco.Cms.Core.Services.IPublicAccessService?,
Umbraco.Cms.Core.Services.IExternalLoginService?,
Umbraco.Cms.Core.Services.IServerRegistrationService?,
Umbraco.Cms.Core.Services.IRedirectUrlService?,
Umbraco.Cms.Core.Services.IConsentService?,
Umbraco.Cms.Core.Services.IKeyValueService?,
Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider?)
Umbraco.Cms.Core.Services.TwoFactorLoginService.TwoFactorLoginService(
Umbraco.Cms.Core.Persistence.Repositories.ITwoFactorLoginRepository,
Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
System.Collections.Generic.IEnumerable,
Microsoft.Extensions.Options.IOptions,
Microsoft.Extensions.Options.IOptions)
Umbraco.Cms.Core.Routing.DefaultUrlProvider.DefaultUrlProvider(
Microsoft.Extensions.Options.IOptionsMonitor,
Microsoft.Extensions.Logging.ILogger,
Umbraco.Cms.Core.Routing.ISiteDomainMapper,
Umbraco.Cms.Core.Web.IUmbracoContextAccessor,
Umbraco.Cms.Core.Routing.UriUtility)
Umbraco.Cms.Core.Persistence.Repositories.IExternalLoginRepository
Umbraco.Cms.Core.Persistence.Repositories.IMacroWithAliasRepository
Umbraco.Cms.Core.Persistence.Repositories.IMemberRepository.SetLastLogin(string, System.DateTime)
Umbraco.Cms.Core.Notifications.UmbracoApplicationComponentsInstallingNotification
Umbraco.Cms.Core.Notifications.UmbracoApplicationMainDomAcquiredNotification
Umbraco.Cms.Core.Notifications.UmbracoApplicationStartingNotification.UmbracoApplicationStartingNotification(Umbraco.Cms.Core.RuntimeLevel)
Umbraco.Cms.Core.Notifications.UmbracoApplicationStoppingNotification.UmbracoApplicationStoppingNotification()
Umbraco.Cms.Core.Models.IContentTypeWithHistoryCleanup
Umbraco.Cms.Core.Models.Language.Language(Umbraco.Cms.Core.Configuration.Models.GlobalSettings, string)
Umbraco.Cms.Core.Models.RelationType.RelationType(string, string, bool, System.Nullable, System.Nullable)
Umbraco.Cms.Core.Models.PublishedContent.PublishedContentType.PublishedContentType(int, string,
Umbraco.Cms.Core.Models.PublishedContent.PublishedItemType,
System.Collections.Generic.IEnumerable,
System.Collections.Generic.IEnumerable,
Umbraco.Cms.Core.Models.ContentVariation,
bool)
Umbraco.Cms.Core.Models.PublishedContent.PublishedContentType.PublishedContentType(int, string,
Umbraco.Cms.Core.Models.PublishedContent.PublishedItemType, System.Collections.Generic.IEnumerable,
System.Func>,
Umbraco.Cms.Core.Models.ContentVariation,
bool)
Umbraco.Cms.Core.Models.Mapping.ContentTypeMapDefinition.ContentTypeMapDefinition(
Umbraco.Cms.Core.Models.Mapping.CommonMapper,
Umbraco.Cms.Core.PropertyEditors.PropertyEditorCollection,
Umbraco.Cms.Core.Services.IDataTypeService,
Umbraco.Cms.Core.Services.IFileService,
Umbraco.Cms.Core.Services.IContentTypeService,
Umbraco.Cms.Core.Services.IMediaTypeService,
Umbraco.Cms.Core.Services.IMemberTypeService,
Microsoft.Extensions.Logging.ILoggerFactory,
Umbraco.Cms.Core.Strings.IShortStringHelper,
Microsoft.Extensions.Options.IOptions,
Umbraco.Cms.Core.Hosting.IHostingEnvironment)
Umbraco.Cms.Core.Models.ContentEditing.UserGroupPermissionsSave.Validate(System.ComponentModel.DataAnnotations.ValidationContext)
Umbraco.Cms.Core.Install.InstallSteps.TelemetryIdentifierStep.TelemetryIdentifierStep(
Microsoft.Extensions.Logging.ILogger,
Microsoft.Extensions.Options.IOptions,
Umbraco.Cms.Core.Configuration.IConfigManipulator)
Umbraco.Cms.Core.IO.ViewHelper.ViewHelper(Umbraco.Cms.Core.IO.IFileSystem)
Umbraco.Cms.Core.HealthChecks.Checks.Security.BaseHttpHeaderCheck.BaseHttpHeaderCheck(
Umbraco.Cms.Core.Hosting.IHostingEnvironment,
Umbraco.Cms.Core.Services.ILocalizedTextService,
string,
string,
string,
bool)
Umbraco.Cms.Core.DependencyInjection.UmbracoBuilderExtensions.AddOEmbedProvider(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)
Umbraco.Cms.Core.DependencyInjection.UmbracoBuilderExtensions.OEmbedProviders(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)
Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings.CharCollection.get
Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings.CharCollection.set
Umbraco.Cms.Core.Composing.IUserComposer
Umbraco.Cms.Core.Security.BackOfficeUserStore.BackOfficeUserStore(
Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
Umbraco.Cms.Core.Services.IUserService,
Umbraco.Cms.Core.Services.IEntityService,
Umbraco.Cms.Core.Services.IExternalLoginService,
Microsoft.Extensions.Options.IOptions,
Umbraco.Cms.Core.Mapping.IUmbracoMapper,
Umbraco.Cms.Core.Security.BackOfficeErrorDescriber,
Umbraco.Cms.Core.Cache.AppCaches)
Umbraco.Cms.Core.Security.MemberUserStore.MemberUserStore(
Umbraco.Cms.Core.Services.IMemberService,
Umbraco.Cms.Core.Mapping.IUmbracoMapper,
Umbraco.Cms.Core.Scoping.ICoreScopeProvider,
Microsoft.AspNetCore.Identity.IdentityErrorDescriber,
Umbraco.Cms.Core.PublishedCache.IPublishedSnapshotAccessor,
Umbraco.Cms.Core.Services.IExternalLoginService)
Umbraco.Cms.Core.Logging.Viewer.ILogViewer.GetLogLevel()
Umbraco.Cms.Core.Logging.Viewer.SerilogLogViewerSourceBase.SerilogLogViewerSourceBase(
Umbraco.Cms.Core.Logging.Viewer.ILogViewerConfig,
Serilog.ILogger)
Umbraco.Cms.Core.Logging.Viewer.SerilogLogViewerSourceBase.GetLogLevel()
Umbraco.Cms.Core.Configuration.JsonConfigManipulator.JsonConfigManipulator(Microsoft.Extensions.Configuration.IConfiguration)
```
#### Umbraco.Cms.Infrastructure
```csharp
Umbraco.Cms.Infrastructure.Persistence.Repositories.Implement.MemberRepository.SetLastLogin(string, System.DateTime)
Umbraco.Cms.Infrastructure.Packaging.PackageMigrationBase.PackageMigrationBase(
Umbraco.Cms.Core.Services.IPackagingService,
Umbraco.Cms.Core.Services.IMediaService,
Umbraco.Cms.Core.IO.MediaFileManager,
Umbraco.Cms.Core.PropertyEditors.MediaUrlGeneratorCollection,
Umbraco.Cms.Core.Strings.IShortStringHelper,
Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider,
Umbraco.Cms.Infrastructure.Migrations.IMigrationContext)
Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator.DatabaseSchemaCreator(
Umbraco.Cms.Infrastructure.Persistence.IUmbracoDatabase?,
Microsoft.Extensions.Logging.ILogger,
Microsoft.Extensions.Logging.ILoggerFactory,
Umbraco.Cms.Core.Configuration.IUmbracoVersion,
Umbraco.Cms.Core.Events.IEventAggregator)
Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreatorFactory.DatabaseSchemaCreatorFactory(
Microsoft.Extensions.Logging.ILogger,
Microsoft.Extensions.Logging.ILoggerFactory,
Umbraco.Cms.Core.Configuration.IUmbracoVersion,
Umbraco.Cms.Core.Events.IEventAggregator)
Umbraco.Cms.Infrastructure.HostedServices.RecurringHostedServiceBase.RecurringHostedServiceBase(
System.TimeSpan,
System.TimeSpan)
Umbraco.Cms.Infrastructure.HostedServices.ReportSiteTask.ReportSiteTask(
Microsoft.Extensions.Logging.ILogger,
Umbraco.Cms.Core.Configuration.IUmbracoVersion,
Microsoft.Extensions.Options.IOptions)
```
#### Umbraco.Cms.Web
```csharp
Umbraco.Cms.Web.Common.Security.ConfigureIISServerOptions
Umbraco.Cms.Web.Common.RuntimeMinification.SmidgeRuntimeMinifier.Reset()
Umbraco.Cms.Web.Common.Middleware.UmbracoRequestMiddleware.UmbracoRequestMiddleware(
Microsoft.Extensions.Logging.ILogger,
Umbraco.Cms.Core.Web.IUmbracoContextFactory,
Umbraco.Cms.Core.Cache.IRequestCache,
Umbraco.Cms.Core.Events.IEventAggregator,
Umbraco.Cms.Core.Logging.IProfiler,
Umbraco.Cms.Core.Hosting.IHostingEnvironment,
Umbraco.Cms.Core.Routing.UmbracoRequestPaths,
Umbraco.Cms.Infrastructure.WebAssets.BackOfficeWebAssets,
Microsoft.Extensions.Options.IOptionsMonitor,
Umbraco.Cms.Core.Services.IRuntimeState,
Umbraco.Cms.Core.Models.PublishedContent.IVariationContextAccessor,
Umbraco.Cms.Core.PublishedCache.IDefaultCultureAccessor)
Umbraco.Cms.Web.Website.Controllers.UmbLoginController.UmbLoginController(
Umbraco.Cms.Core.Web.IUmbracoContextAccessor,
Umbraco.Cms.Infrastructure.Persistence.IUmbracoDatabaseFactory,
Umbraco.Cms.Core.Services.ServiceContext,
Umbraco.Cms.Core.Cache.AppCaches,
Umbraco.Cms.Core.Logging.IProfilingLogger,
Umbraco.Cms.Core.Routing.IPublishedUrlProvider,
Umbraco.Cms.Web.Common.Security.IMemberSignInManager)
Umbraco.Cms.Web.BackOffice.Trees.MemberTypeAndGroupTreeControllerBase.MemberTypeAndGroupTreeControllerBase(
Umbraco.Cms.Core.Services.ILocalizedTextService,
Umbraco.Cms.Core.UmbracoApiControllerTypeCollection,
Umbraco.Cms.Core.Trees.IMenuItemCollectionFactory,
Umbraco.Cms.Core.Events.IEventAggregator)
Umbraco.Cms.Web.BackOffice.Controllers.CurrentUserController.CurrentUserController(
Umbraco.Cms.Core.IO.MediaFileManager,
Microsoft.Extensions.Options.IOptions,
Umbraco.Cms.Core.Hosting.IHostingEnvironment,
Umbraco.Cms.Core.Media.IImageUrlGenerator,
Umbraco.Cms.Core.Security.IBackOfficeSecurityAccessor,
Umbraco.Cms.Core.Services.IUserService,
Umbraco.Cms.Core.Mapping.IUmbracoMapper,
Umbraco.Cms.Core.Security.IBackOfficeUserManager,
Microsoft.Extensions.Logging.ILoggerFactory,
Umbraco.Cms.Core.Services.ILocalizedTextService,
Umbraco.Cms.Core.Cache.AppCaches,
Umbraco.Cms.Core.Strings.IShortStringHelper,
Umbraco.Cms.Web.Common.Security.IPasswordChanger)
Umbraco.Cms.Web.BackOffice.Controllers.EntityController.GetUrlsByUdis(Umbraco.Cms.Core.Udi[], string?)
Umbraco.Cms.Web.BackOffice.Controllers.HelpController.HelpController(Microsoft.Extensions.Logging.ILogger)
Umbraco.Cms.Web.BackOffice.Controllers.LanguageController.LanguageController(
Umbraco.Cms.Core.Services.ILocalizationService,
Umbraco.Cms.Core.Mapping.IUmbracoMapper,
Microsoft.Extensions.Options.IOptionsSnapshot)
Umbraco.Cms.Web.BackOffice.Controllers.LogViewerController.LogViewerController(Umbraco.Cms.Core.Logging.Viewer.ILogViewer)
Umbraco.Cms.Web.BackOffice.Controllers.LogViewerController.GetLogLevel()
Umbraco.Cms.Web.BackOffice.Controllers.MediaController.GetPagedReferences(int, string, int, int)
Umbraco.Cms.Web.BackOffice.Controllers.MemberTypeController.GetAllTypes()
Umbraco.Cms.Web.BackOffice.Controllers.TemplateController.TemplateController(
Umbraco.Cms.Core.Services.IFileService,
Umbraco.Cms.Core.Mapping.IUmbracoMapper,
Umbraco.Cms.Core.Strings.IShortStringHelper)
```
#### Umbraco.Cms.Tests
```csharp
Umbraco.Cms.Tests.Common.Testing.TestOptionAttributeBase.ScanAssemblies
```
### Code moved to new assemblies and namespaces
The following have been moved to new assemblies and their namespaces have been updated accordingly.
#### Umbraco.Extensions
```csharp
Umbraco.Extensions.NPocoDatabaseExtensions.ConfigureNPocoBulkExtensions()
Umbraco.Extensions.UmbracoBuilderExtensions.AddUmbracoImageSharp(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)
```
#### Umbraco.Cms.Web
```csharp
Umbraco.Cms.Web.Common.Media.ImageSharpImageUrlGenerator
Umbraco.Cms.Web.Common.ImageProcessors.CropWebProcessor
Umbraco.Cms.Web.Common.DependencyInjection.ConfigureImageSharpMiddlewareOptions
Umbraco.Cms.Web.Common.DependencyInjection.ConfigurePhysicalFileSystemCacheOptions
```
#### Umbraco.Cms.Infrastructure
```csharp
Umbraco.Cms.Infrastructure.Persistence.LocalDb
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.RetryPolicyFactory
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingMode
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingType
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottledResourceType
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.ThrottlingCondition
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.Strategies.NetworkConnectivityErrorDetectionStrategy
Umbraco.Cms.Infrastructure.Persistence.FaultHandling.Strategies.SqlAzureTransientErrorDetectionStrategy
```
### New interface methods
A few interfaces have been merged, adding new members to the original interfaces.
#### Umbraco.Cms.Core
```csharp
Umbraco.Cms.Core.Services.IMacroService.GetAll(params string[])
Umbraco.Cms.Core.Persistence.Repositories.IMacroRepository.GetByAlias(string)
Umbraco.Cms.Core.Persistence.Repositories.IMacroRepository.GetAllByAlias(string[])
Umbraco.Cms.Core.Services.ITwoFactorLoginService.DisableWithCodeAsync(string, System.Guid, string)
Umbraco.Cms.Core.Services.ITwoFactorLoginService.ValidateAndSaveAsync(string, System.Guid, string, string)
Umbraco.Cms.Core.Models.IContentType.HistoryCleanup
Umbraco.Cms.Core.Media.IImageDimensionExtractor.SupportedImageFileTypes
```
### No-Operation methods removed
A method not doing anything for the last couple of major releases have been removed.
#### Umbraco.Cms.Core
```csharp
Umbraco.Cms.Core.Services.IMembershipMemberService.SetLastLogin(string, System.DateTime)
```
### Changes due to models made immutable
A single model have been made immutable, so the default constructor and the setters are not available anymore.
#### Umbraco.Cms.Infrastructure
```csharp
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.ContentData()
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Name.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.UrlSegment.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.VersionId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.VersionDate.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.WriterId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.TemplateId.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Published.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.Properties.set
Umbraco.Cms.Infrastructure.PublishedCache.DataSource.ContentData.CultureInfos.set
```
### Classes that does not inherit from base type anymore
The following classes now directly inherit from OEmbedProviderBase instead of EmbedProviderBase.
#### Umbraco.Cms.Core
```csharp
Umbraco.Cms.Core.Media.EmbedProviders.DailyMotion
Umbraco.Cms.Core.Media.EmbedProviders.Flickr
Umbraco.Cms.Core.Media.EmbedProviders.GettyImages
Umbraco.Cms.Core.Media.EmbedProviders.Giphy
Umbraco.Cms.Core.Media.EmbedProviders.Hulu
Umbraco.Cms.Core.Media.EmbedProviders.Issuu
Umbraco.Cms.Core.Media.EmbedProviders.Kickstarter
Umbraco.Cms.Core.Media.EmbedProviders.Slideshare
Umbraco.Cms.Core.Media.EmbedProviders.Soundcloud
Umbraco.Cms.Core.Media.EmbedProviders.Ted
Umbraco.Cms.Core.Media.EmbedProviders.Twitter
Umbraco.Cms.Core.Media.EmbedProviders.Vimeo
Umbraco.Cms.Core.Media.EmbedProviders.YouTube
```
Umbraco 10
### [Update 'diff' from 3.5.0 to 5.0.0](https://github.com/umbraco/Umbraco-CMS/issues/12337)
The `diff` library used in the Backoffice client has been updated and introduces a breaking change since the exposed global object has been renamed from `JsDiff` to `Diff`.
### [Content Schedule performance](https://github.com/umbraco/Umbraco-CMS/pull/11398)
Removes mutable ContentSchedule property from `IContent/Content` to `read/write` content schedules.
Use *IContentService.GetContentScheduleByContentId && IContentService.PersistContentSchedule* or the optional *contentSchedule parameter* on *IContentService.Save* instead.
### [Removed redundant event handling code](https://github.com/umbraco/Umbraco-CMS/pull/11842)
* Removed public methods: `PublishedSnapshotServiceEventHandler.Dispose`, `PublishedSnapshotServiceEventHandler.Dispose(bool)`, and `.PublishedSnapshotServiceEventHandler.Initialize`.
* Removed public `ctor`.
### [Scope provider cleanup](https://github.com/umbraco/Umbraco-CMS/pull/11859)
* Some public classes in the `Cms.Core.Services` namespace have moved assembly from **`Umbraco.Cms.Infrastructure`** to **`Umbraco.Cms.Core`**.
* These same public classes have changed namespace from **`Umbraco.Cms.Core.Services.Implement`** to **`Umbraco.Cms.Core.Services`**.
### [Update to NPoco5](https://github.com/umbraco/Umbraco-CMS/pull/11880)
NPoco types and interfaces are part of our public interface which means that this upgrade imposes breaking changes.
### [SQLite support](https://github.com/umbraco/Umbraco-CMS/pull/11922)
* Removed support for Microsoft SQL Server Compact (SQL CE).
* Removed `ReadLock` and `WriteLock` methods from `ISqlSyntaxProvider` interface. Use `IDistributedLockingMechanism` (or IScope which delegates to `IDistributedLockingMechanism`) instead.
* Constants for SQL Server provider name moved+consolidated from `Core.Constants.DatabaseProviders` and `Core.Constants.-DbProviderNames` to `Umbraco.Cms.Persistence.SqlServer.Constants`
* Some SQL Server related services moved from the `Umbraco.Infrastructure` project to the new `Umbraco.Cms.Persistence`.
* SqlServer project with altered namespaces e.g. `SqlServerSyntaxProvider`, `SqlServerBulkSqlInsertProvider`, `SqlServerDatabaseCreator`.
**Added the following methods/properties to ISqlSyntaxProvider. These must be implemented in any downstream implementation e.g:**
* `ISqlSyntaxProvider.HandleCreateTable(IDatabase,TableDefinition,Boolean)`
* `ISqlSyntaxProvider.GetFieldNameForUpdate()`
* `ISqlSyntaxProvider.GetColumn(DatabaseType,String,String,String,String,Boolean)`
* `ISqlSyntaxProvider.InsertForUpdateHint(Sql)`
* `ISqlSyntaxProvider.AppendForUpdateHint(Sql)`
* `ISqlSyntaxProvider.LeftJoinWithNestedJoin(Sql,Func,String)`
### [Update to ImageSharp v2](https://github.com/umbraco/Umbraco-CMS/pull/12185)
#### Update dependency versions
* `SixLabors.ImageSharp` from 1.0.4 to 2.1.1
* `SixLabors.ImageSharp.Web` from 1.0.5 to 2.0.0
Renamed the `CachedNameLength` property to `CacheHashLength` on **ImagingCacheSettings**.
Moved **ImageSharpImageUrlGenerator** from project `Umbraco.Infrastructure` to `Umbraco.Web.Common` and updated the corresponding namespace and DI registration (from `AddCoreInitialServices()` to `AddUmbracoImageSharp()`);
Moved **ImageSharp** configuration from the `AddUmbracoImageSharp()` extension method into separate `IConfigureOptions<>` implementations:
* The middleware is configured in ConfigureImageSharpMiddlewareOptions (which also replaces ImageSharpConfigurationOptions that previously only set the default ImageSharp configuration);
* The default physical cache is configured in ConfigurePhysicalFileSystemCacheOptions.
### [Migrate Member properties to columns on the Member table](https://github.com/umbraco/Umbraco-CMS/pull/12205)
This is breaking because it is no longer possible to access the properties listed below through the *IMember.Properties* collection. You must now access them through their specific properties that is *IMember.IsLockedOut*.
* `umbracoMemberFailedPasswordAttempts`
* `umbracoMemberApproved`
* `umbracoMemberLockedOut`
* `umbracoMemberLastLockoutDate`
* `umbracoMemberLastLogin`
* `umbracoMemberLastPasswordChangeDate`
Additionally, when previously you resolved a Member as published content, all the default properties would be there twice. For instance, `IsLockedOut` would be there both as a property with the alias `umbracoMemberLockedOut` and with the alias `IsLockedOut`. Now it'll only be there once, with the alias being the name of the property, so `IsLockedOut` in this instance.
Lastly the nullable dates on a user, i.e. `LastLoginLate` will now be null instead of `DateTime.MinValue` when getting a user with the UserService.
### [Update examine to version 3](https://github.com/umbraco/Umbraco-CMS/pull/12307)
#### Examine 3 breaking changes
* `ValueSet` immutable.
* `ValueSetValidationResult` is renamed to `ValueSetValidationStatus` and `ValueSetValidationResult` is now a type.
### [Async support for content finders](https://github.com/umbraco/Umbraco-CMS/pull/12340)
```csharp
bool TryFindContent(IPublishedRequestBuilder request);
```
Has changed to:
```csharp
Task TryFindContent(IPublishedRequestBuilder request);
```
### [Improve redirect Content finder scalability](https://github.com/umbraco/Umbraco-CMS/pull/12341)
* Added more methods to `IRedirectUrlRepository` and `IRedirectUrlService.cs`.
### [Fix Block List settings exception and optimize PVCs](https://github.com/umbraco/Umbraco-CMS/pull/12342)
* Added a new method on `IPublishedModelFactory`: Type `GetModelType(string? alias)`;
* The generic types of a `BlockListItem`instance in the`BlockListModel`returned by`BlockListPropertyValueConverter`is now determined by calling this new method, which can be different and cause a`ModelBindingException\` in your views.
### [Async tree search](https://github.com/umbraco/Umbraco-CMS/pull/12344)
```csharp
IEnumerable Search(string query, int pageSize, long pageIndex, out long totalFound, string? searchFrom
= null)
```
Has changed to:
```csharp
Task SearchAsync(string query, int pageSize, long pageIndex, string? searchFrom = null);
```
### [Moved StackQueue to correct namespace](https://github.com/umbraco/Umbraco-CMS/pull/12347)
StackQueue has been moved from `Umbraco.Core.Collections` to the `Umbraco.Cms.Core.Collections` namespace.
### Globalsetting SqlWriteLockTimeOut has been removed
This setting has been superseded by `DistributedLockingWriteLockDefaultTimeout`.
### GlobalSetting UmbracoPath cannot be configured
It is no longer possible to rename the `/Umbraco` folder path using configuration. The property still exists but is hardcoded to `/Umbraco` and will be removed in Umbraco 12, planned for release in June 2023.
## Release notes
You can find a list of all the released Umbraco versions on [Our Umbraco](https://our.umbraco.com/download/releases/) website. When you visit Our Umbraco website, click on the version number to view the changes made in that specific version.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.umbraco.com/umbraco-cms/19.latest/get-started/upgrading-and-migrating/version-specific.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.