12.latest
Cloud Heartcore
DXP
Marketplace

Version Specific Upgrades

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

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

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

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

Breaking changes

Umbraco 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.Publish2(System.Collections.Generic.IEnumerable{0})

  • Umbraco.Cms.Core.Events.IEventAggregator.PublishAsync2(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.

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.

The breaking changes in TinyMCE are also documented in the official migration guides for version 4 to 5 and from version 5 to 6.

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.

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

Umbraco.Extensions.ServiceCollectionExtensions.AddUnique<TImplementing>(Microsoft.Extensions.DependencyInjection.IServiceCollection)

Umbraco.Extensions.EnumExtensions.HasFlagAll<T>(T, T)

Umbraco.Extensions.FriendlyImageCropperTemplateExtensions.GetLocalCropUrl(Umbraco.Cms.Core.Models.MediaWithCrops, string, string?)

Umbraco.Cms.Core

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.Security.IExternalLogin>)

Umbraco.Cms.Core.Services.ExternalLoginService.Save(int,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Security.IExternalLoginToken>)

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<System.Globalization.CultureInfo, System.Collections.Generic.IDictionary<string, System.Collections.Generic.IDictionary<string, string>>>,
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Core.Services.LocalizedTextService>)

Umbraco.Cms.Core.Services.ServiceContext.ServiceContext(
    System.Lazy<Umbraco.Cms.Core.Services.IPublicAccessService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IDomainService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IAuditService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ILocalizedTextService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ITagService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IUserService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMediaService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMediaTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IDataTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IFileService>?,
    System.Lazy<Umbraco.Cms.Core.Services.ILocalizationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IPackagingService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IServerRegistrationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IEntityService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IRelationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMacroService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberTypeService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IMemberGroupService>?,
    System.Lazy<Umbraco.Cms.Core.Services.INotificationService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IExternalLoginService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IRedirectUrlService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IConsentService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IKeyValueService>?,
    System.Lazy<Umbraco.Cms.Core.Services.IContentTypeBaseServiceProvider>?)

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<Umbraco.Cms.Core.Security.ITwoFactorProvider>,
    Microsoft.Extensions.Options.IOptions<Microsoft.AspNetCore.Identity.IdentityOptions>,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Security.BackOfficeIdentityOptions>)

Umbraco.Cms.Core.Routing.DefaultUrlProvider.DefaultUrlProvider(
    Microsoft.Extensions.Options.IOptionsMonitor<Umbraco.Cms.Core.Configuration.Models.RequestHandlerSettings>,
    Microsoft.Extensions.Logging.ILogger<Umbraco.Cms.Core.Routing.DefaultUrlProvider>,
    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.Guid>, System.Nullable<System.Guid>)

Umbraco.Cms.Core.Models.PublishedContent.PublishedContentType.PublishedContentType(int, string,
    Umbraco.Cms.Core.Models.PublishedContent.PublishedItemType,
    System.Collections.Generic.IEnumerable<string>,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Models.PublishedContent.PublishedPropertyType>,
    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<string>,
    System.Func<Umbraco.Cms.Core.Models.PublishedContent.IPublishedContentType,
    System.Collections.Generic.IEnumerable<Umbraco.Cms.Core.Models.PublishedContent.IPublishedPropertyType>>,
    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.Configuration.Models.GlobalSettings>,
    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<Umbraco.Cms.Core.Install.InstallSteps.TelemetryIdentifierStep>,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>,
    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<T>(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.Configuration.Models.GlobalSettings>,
    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

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<Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator>,
    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<Umbraco.Cms.Infrastructure.Migrations.Install.DatabaseSchemaCreator>,
    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.Infrastructure.HostedServices.ReportSiteTask>,
    Umbraco.Cms.Core.Configuration.IUmbracoVersion,
    Microsoft.Extensions.Options.IOptions<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>)

Umbraco.Cms.Web

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.Web.Common.Middleware.UmbracoRequestMiddleware>,
    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<Smidge.Options.SmidgeOptions>,
    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.Configuration.Models.ContentSettings>,
    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.Core.Security.BackOfficeIdentityUser>)

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.HelpController>)

Umbraco.Cms.Web.BackOffice.Controllers.LanguageController.LanguageController(
    Umbraco.Cms.Core.Services.ILocalizationService,
    Umbraco.Cms.Core.Mapping.IUmbracoMapper,
    Microsoft.Extensions.Options.IOptionsSnapshot<Umbraco.Cms.Core.Configuration.Models.GlobalSettings>)

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

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

Umbraco.Extensions.NPocoDatabaseExtensions.ConfigureNPocoBulkExtensions()

Umbraco.Extensions.UmbracoBuilderExtensions.AddUmbracoImageSharp(Umbraco.Cms.Core.DependencyInjection.IUmbracoBuilder)

Umbraco.Cms.Web

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

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

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

Umbraco.Cms.Core.Services.IMembershipMemberService<T>.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

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

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

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

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

  • Removed public methods: PublishedSnapshotServiceEventHandler.Dispose, PublishedSnapshotServiceEventHandler.Dispose(bool), and .PublishedSnapshotServiceEventHandler.Initialize.

  • Removed public ctor.

Scope provider cleanup

  • 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

NPoco types and interfaces are part of our public interface which means that this upgrade imposes breaking changes.

SQLite support

  • 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<Sql,Sql>,String)

Update to ImageSharp v2

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

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

Examine 3 breaking changes:

  • ValueSet immutable.

  • ValueSetValidationResult is renamed to ValueSetValidationStatus and ValueSetValidationResult is now a type.

Async support for content finders

bool TryFindContent(IPublishedRequestBuilder request);

Has changed to:

Task<bool> TryFindContent(IPublishedRequestBuilder request);

Improve redirect Content finder scalability

  • Added more methods to IRedirectUrlRepository and IRedirectUrlService.cs.

Fix Block List settings exception and optimize PVCs

  • Added a new method on IPublishedModelFactory: Type GetModelType(string? alias);

  • The generic types of a BlockListItem<TContent, TSettings>instance in theBlockListModelreturned byBlockListPropertyValueConverteris now determined by calling this new method, which can be different and cause aModelBindingException` in your views.

Async tree search

IEnumerable<SearchResultEntity?> Search(string query, int pageSize, long pageIndex, out long totalFound, string? searchFrom 
= null)

Has changed to:

Task<EntitySearchResults> SearchAsync(string query, int pageSize, long pageIndex, string? searchFrom = null);

Moved StackQueue to correct namespace

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 website. When you visit Our Umbraco website, click on the version number to view the changes made in that specific version.

Find your upgrade path

Are you looking to upgrade an Umbraco Cloud project from 9 to 10? Follow the guide made for Upgrading your project from Umbraco 9 to 10 instead, as it requires a few steps specific to Umbraco Cloud.

10.latest to the latest Umbraco version

It might be necessary to delete all of the bin and obj directories in each of the projects of your solution. It has been observed that Visual Studio's "Clean Solution" option is sometimes not enough.

You can upgrade from Umbraco 10 to the latest version directly. If you choose to skip upgrading to version 11, you will no longer receive warning messages for obsolete features. However, if you do skip this version, any breaking changes will no longer compile.

It is recommended to upgrade to the closest Long-term Support (LTS) major version before upgrading to the latest version. For Umbraco 10, the closest long-term support version is Umbraco 12 so a direct upgrade is possible.

9.latest to 10

Important: .NET version 6.0.5 is the minimum required version for Umbraco 10 to be able to run. You can check with dotnet --list-sdks what your latest installed Software Development Kit (SDK) version is. The latest SDK version 6.0.301 includes .NET 6.0.6, while SDK version 6.0.300 includes .NET 6.0.5.

Watch the 'Upgrading from Umbraco 9 to Umbraco 10 video tutorial' for a complete walk-through of all the steps.

The upgrade path between Umbraco 9 and Umbraco 10 can be done directly by upgrading your project using NuGet. You will need to ensure the packages you are using are available in Umbraco 10.

SQL CE is no longer a supported database engine

There is no official migration path from SQL CE to another database engine.

The following options may suit your needs:

  • Follow a community guide to migrate from a SQL CE database to SQL Server, like the article by Jan Reilink

  • Setup a new database for v10 and use uSync to transfer document types and content across.

  • Setup a new database for v10 and use a premium tool such as redgate SQL Data Compare to copy database contents across.

  • Setup a new database for v10 and use a premium tool such as Umbraco Deploy to transfer document types and content across.

Steps to upgrade using Visual Studio

It's recommended that you upgrade the site offline, and test the upgrade fully before deploying it to the production environment.

  1. Stop your site in IIS to prevent any changes being made to the database or filesystem while you are upgrading.

  2. Open your Umbraco 9 project in Visual Studio.

  3. Right-click on the project name in the Solution Explorer and select Properties.

  4. Select .NET 6.0 from the Target Framework drop-down.

  5. Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...

  6. Go to the Installed tab in the NuGet Package manager.

  7. Choose Umbraco.Cms.

  8. Select 10.0.0 from the Version drop-down and click Install to upgrade your project to version 10.

  9. Update Program.cs to the following:

public class Program
{
    public static void Main(string[] args)
        => CreateHostBuilder(args)
            .Build()
            .Run();

    // The calls to `ConfigureUmbracoDefaults` and `webBuilder.UseStaticWebAssets()` are new.
    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureUmbracoDefaults()
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStaticWebAssets();
                webBuilder.UseStartup<Startup>();
            });
}

  1. Remove the following files and folders:

    • /wwwroot/umbraco

    • /umbraco/PartialViewMacros

    • /umbraco/UmbracoBackOffice

    • /umbraco/UmbracoInstall

    • /umbraco/UmbracoWebsite

    • /umbraco/config/lang

    • /umbraco/config/appsettings-schema.json

  2. If using Umbraco Forms, update your files and folders according to the Upgrading - version specific for version 10 article.

  3. Restart your site in IIS, build and run your project to finish the installation of Umbraco 10.

To re-enable the appsettings IntelliSense, you must update your schema reference in the appsettings.json file and any other appsettings.{Environment}.json files from:

"$schema": "./umbraco/config/appsettings-schema.json",

To:

"$schema": "./appsettings-schema.json",

To upgrade to Umbraco 10, your database needs to be at least on Umbraco 8.18.

Upgrade of any publicly hosted environment

When the upgrade is completed and tested, and prior to deploying to any publicly accessible environment, you should consider the following:

  1. Ensure you have backups for both the database and the file system.

  2. Stop the site so it is not accessible during the upgrade process.

  3. Delete the relevant folders from the filesystem prior to deploying:

    • /wwwroot/umbraco

    • /umbraco/PartialViewMacros

    • /umbraco/UmbracoBackOffice

    • /umbraco/UmbracoInstall

    • /umbraco/UmbracoWebsite

    • /umbraco/config/lang

    • /umbraco/config/appsettings-schema.json

  4. If you are using Umbraco Forms, update your files and folders according to the Upgrading - version specific for version 10 article.

  5. Deploy the site how you normally would to your public facing environment.

  6. Start the site. At this point it will launch and upgrade the database, after which the site should become accessible and your upgrade is complete.

  7. Check the logs for any errors which may have occurred during the upgrade process.

8.latest to 9

There is no direct upgrade path from Umbraco 8 to Umbraco 9. It is however possible to migrate from Umbraco 8 sites to Umbraco 9 sites.

You can reuse your content by restoring your Umbraco 8 database into a new database used for an Umbraco 9 site.

You need to ensure the packages you are using are available in Umbraco 9, and you will need to reimplement your custom code and templates.

The direct upgrade path is not possible because the codebase has been fundamentally updated in Umbraco 9. The underlying web framework has been updated from ASP.NET to ASP.NET Core.

It is not possible to take this step while maintaining full compatibility with Umbraco 8.

8.0.0 to 8.1.0

There are a few breaking changes from 8.0.x to 8.1.0. Make sure to check the full list.

IPublishedContent breaking changes in 8.1.0

Due to the changes in IPublishedContent there are a few steps you will need to take, to make sure that your site works.

The IPublishedContent interface is central to Umbraco, as it represents published content and media items at the rendering layer level. This could be in controllers or views. In other words, it is the interface that is used everywhere when building sites.

The introduction of multilingual support in version 8 required changes to the interface. For instance, a property value could be obtained with GetPropertyValue(alias) in version 7. Version 8 requires a new parameter for culture, and the call thus became Value(alias, culture).

In the excitement of the version 8 release, we assumed that IPublishedContent was "done". By our tests, everything was looking good. However, feedback from early testers showed that the interface was in some places odd or inconsistent or had issues.

Fixing the bugs is a requirement. Some of the required bug fixes could not be achieved without introducing some breaking changes.

At that point, we decided to give IPublishedContent some love. We fixed the bugs and made it clean, friendly, discoverable, and predictable for the entire life of version 8.

Breaking changes to such a central interface is not something we take lightly. Even though they do not impact the "concepts" nor require heavy refactoring, they may demand an amount of small fixes here and there.

The general idea underlying these changes is that:

  • The proper way to retrieve "something" from an IPublishedContent instance is always through a method, for example: Children(). And, when that method can be multilingual, the method accepts a culture parameter, which can be left null to get the "current" culture value.

  • To reduce the amount of breaking changes, and to simplify things for non-multilingual sites, existing properties such as document.Name and document.Children (and others) still exist, and return the value for the current culture. In other words, these properties are now implemented as document.Name => document.Name() or document.Children => document.Children().

The rest of this document presents each change in details.

More interfaces

It was possible to mock and test the IPublishedContent interface in version 7. It has been improved in version 8, but it still relies on concrete PublishedContentType and PublishedPropertyType classes to represent the content types, which complicates things.

In version 8.1, these two classes are abstracted as IPublishedContentType and IPublishedPropertyType, thus making IPublishedContent easier to mock and test.

CHANGE: This impacts every method accepting or returning a content type. For instance, the signature of most IPropertyValueConverter methods changes. References to PublishedContentType must be replaced with references to IPublishedContentType.

The following IPublishedContent members change:

Name

The document.Name property is complemented by the document.Name(string culture = null) extension method. The property returns the name for the current culture. The document.GetCulture(...).Name syntax is removed.