1 of 7

Upgrade your project

This is the guide for upgrading existing installations in general.

In this article, you will find everything you need to upgrade your Umbraco CMS project.

You will find instructions on how to upgrade to a new minor or major version as well as how to run upgrades unattended.

Before you upgrade
Upgrade to a new Major
Upgrade to a new Minor
Run an unattended upgrade

Before you upgrade

The following lists a few things to be aware of before initiating an upgrade of your Umbraco CMS project.

Sometimes there are exceptions to general upgrade guidelines. These are listed in the version-specific guide. Be sure to read this article before moving on.
Check if your setup meets the requirements for the new versions you will be upgrading your project to.
Things may go wrong for different reasons. Be sure to ALWAYS keep a backup of both your site's files and the database. This way you can always return to a version that you know works.
Before upgrading to a new major version, check if the packages you're using are compatible with the version you're upgrading to. On the package's download page, in the Project compatibility area, click View details to check version-specific compatibility.

It is necessary to run the upgrade installer on each environment of your Umbraco site. This means that you need to repeat the steps below on each of your environments in order to complete the upgrade.

Legacy Umbraco

The steps outlined in this article apply to modern Umbraco from version 10 and later versions.

Are you upgrading to a minor for Umbraco 6, 7, or 8 you can find the appropriate guide below:

Upgrade to a new Major

You can upgrade to a new major of Umbraco CMS directly by using NuGet.

Switching to a new major of Umbraco CMS also means switching to a new .NET version. You need to make sure that any packages used on your site are compatible with this version before upgrading.

The package compatibility can be checked on the package's download page. Locate the Project compatibility area and select View details to check version-specific compatibility.

Choose the correct .NET version

Use the table below to determine which .NET version to upgrade to when going through the steps below.

Upgrade your project using Visual Studio

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

Stop your site in IIS to prevent any changes from being made while you are upgrading.
Open your Umbraco project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select the .NET version from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Upgrade Umbraco.Cms.
a. Select the correct version from the Version drop-down.
b. Click Install to upgrade your project.

If you have other packages installed such as Umbraco Forms, then before upgrading Umbraco.CMS you will need to upgrade the packages first. Consult the version specific upgrade notes for Umbraco Forms if relevant.

Make sure that your connection string has TrustServerCertificate=True in order to complete the upgrade successfully:

"ConnectionStrings": {
    "umbracoDbDSN": "Server=YourLocalSQLServerHere;Database=NameOfYourDatabaseHere;User Id=NameOfYourUserHere;Password=YourPasswordHere;TrustServerCertificate=True"
}

Restart your site in IIS, then build and run your project to finish the installation.

In Umbraco 13, we have moved to using the Minimal Hosting Model.

If you have added custom code to the startup.cs file, we recommend moving the code into a Composer after upgrading.

If your database experiences timeout issues after an upgrade, it might be due to ASP.NET Core Module's 'startupTimeLimit' configuration.

To fix the issue, try increasing the startupTimeLimit in the web.config file. Additionally, you can set the Connection Timeout value in the ConnectionString in the appsettings.json file.

Upgrade to a new Minor

NuGet installs the latest version of the package when you use the dotnet add package command unless you specify a package version:

dotnet add package Umbraco.Cms --version <VERSION>

Add a package reference to your project by executing the dotnet add package Umbraco.Cms command in the directory that contains your project file.

Run dotnet restore to install the package.

For v9: If you are using SQL CE in your project you will need to run dotnet add package Umbraco.Cms.SqlCe --version <VERSION> before running the dotnet restore command. From v10, SQL CE has been replaced with SQLite so a dotnet restore should be sufficient. If this is not working then you will need to run dotnet add package Umbraco.Cms.Persistence.Sqlite --version <VERSION> and then dotnet restore.

When the command completes, open the .csproj file to make sure the package reference was updated:

.csproj

<ItemGroup>
  <PackageReference Include="Umbraco.Cms" Version="x.x.x" />
</ItemGroup>

Run an unattended upgrade

When upgrading your Umbraco project, it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.

Below you will find the steps you need to take in order to upgrade your project unattended.

Are you running a load balanced setup with multiple servers and environments?

Check out the section about Unattended upgrades in a load balanced setup.

Enable the unattended upgrade feature

Add the Umbraco:Cms:Unattended:UpgradeUnattended configuration key.
Set the value of the key to true.

appsettings.json

{
    "Umbraco": {
        "CMS": {
            "Unattended": {
                "UpgradeUnattended": true
            }
        }
    }
}

Run the upgrade

With the correct configuration applied, the project will be upgraded on the next boot.

Boot order

The Runtime level will use Run instead of Upgrade to allow the website to continue to boot up directly after the migration is run. This happens instead of initiating the otherwise required restart.

The upgrade is run after Composers but before Components and the UmbracoApplicationStartingNotification. This is because the migration requires services that are registered in Composers and Components require that Umbraco and the database are ready.

Unattended upgrades in a load balanced setup

Follow the steps outlined below to use unattended upgrades in a load balanced setup.

Upgrade Umbraco via NuGet (see instructions above)
Deploy to all environments.
Set the Umbraco:CMS:Unattended:UpgradeUnattended configuration key to true for the Main server only.
Boot the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Boot the Read-Only servers and make sure they do not show the “upgrade required” screen.

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 to complete the upgrade of your project.

Breaking changes

Umbraco 13

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

You can find more information about all breaking changes for v13.0.0 on website.

Note: 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.

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 .

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 .

The breaking changes in TinyMCE are also documented in the official migration guides for and from .

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 .

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.Cms.Core

Umbraco.Cms.Infrastructure

Umbraco.Cms.Web

Umbraco.Cms.Tests

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.Cms.Web

Umbraco.Cms.Infrastructure

New interface methods

A few interfaces have been merged, adding new members to the original interfaces.

Umbraco.Cms.Core

No-Operation methods removed

A method not doing anything for the last couple of major releases have been removed.

Umbraco.Cms.Core

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

Classes that does not inherit from base type anymore

The following classes now directly inherit from OEmbedProviderBase instead of EmbedProviderBase.

Umbraco.Cms.Core

Umbraco 10

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.

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 public methods: PublishedSnapshotServiceEventHandler.Dispose, PublishedSnapshotServiceEventHandler.Dispose(bool), and .PublishedSnapshotServiceEventHandler.Initialize.
Removed public ctor.

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.

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

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

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.

Examine 3 breaking changes:

ValueSet immutable.
ValueSetValidationResult is renamed to ValueSetValidationStatus and ValueSetValidationResult is now a type.

Has changed to:

Added more methods to IRedirectUrlRepository and IRedirectUrlService.cs.

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.

Has changed to:

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

Find your upgrade path

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 versions 11 and 12, you will no longer receive warning messages for obsolete features. However, if you do skip these versions, any breaking changes will no longer compile.

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.

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:

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.

Stop your site in IIS to prevent any changes being made to the database or filesystem while you are upgrading.
Open your Umbraco 9 project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select .NET 6.0 from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Choose Umbraco.Cms.
Select 10.0.0 from the Version drop-down and click Install to upgrade your project to version 10.
Update Program.cs to the following:

Remove the following files and folders:
- /wwwroot/umbraco
- /umbraco/PartialViewMacros
- /umbraco/UmbracoBackOffice
- /umbraco/UmbracoInstall
- /umbraco/UmbracoWebsite
- /umbraco/config/lang
- /umbraco/config/appsettings-schema.json
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:

To:

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:

Ensure you have backups for both the database and the file system.
Stop the site so it is not accessible during the upgrade process.
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
Deploy the site how you normally would to your public facing environment.
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.
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

IPublishedContent breaking changes in 8.1.0

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.

CHANGE: Calls to document.GetCulture(culture).Name must be replaced with document.Name(culture).

UrlSegment

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

CHANGE: Calls to document.GetCulture(culture).UrlSegment must be replaced with document.UrlSegment(culture).

Culture

The document.GetCulture() method is removed. The proper way to get a culture date is document.CultureDate(string culture = null). The document.Cultures property now returns the invariant culture, for invariant documents.

CHANGE: Calls to document.GetCulture(culture).Date must be replaced with document.CultureDate(culture). Calls to document.Cultures must take into account the invariant culture.

Children

The document.Children property is complemented by the document.Children(string culture = null) extension method which, when a culture is specified always return children available for the specified culture. The property returns the children available for the current culture.

A new document.ChildrenForAllCultures property is introduced, which returns all children, regardless of whether they are available for a culture or not.

CHANGE: Calls to document.Children may have to be replaced by document.ChildrenForAllCultures depending on if the 8.0.x usage of this was relying on it returning unfiltered/all children regardless of the current routed culture.

Url

The document.Url property is complemented by the document.Url(string culture = null, UrlMode mode = UrlMode.Auto) extension method. The document.GetUrl(...) and document.UrlAbsolute() methods are removed. The UrlProviderMode enumeration is renamed UrlMode.

CHANGE: Calls to document.GetUrl(...) must be replaced with document.Url(...). Calls to document.UrlAbsolute() must be replaced with document.Url(mode: UrlMode.Absolute).

UmbracoContext

Due to the UrlProviderMode enumeration being renamed UrlMode, the signature of some overloads of the Url(...) method has changed. Methods that do not have a mode parameter remain unchanged.

CHANGE: Code such as context.Url(1234, UrlProviderMode.Absolute) must become context.Url(1234, UrlMode.Absolute).

The UmbracoContext class gives access to the rendering layer, which is more than a "cache". To reflect this, its ContentCache and MediaCache properties are renamed Content and Media. However, the old properties remain as obsolete properties.

CHANGE: None required in 8.1, but code such as context.ContentCache.GetById(1234) should eventually be converted to context.Content.GetById(1234) as the obsolete properties may be removed in a further release.

GetCulture

Because that method is useful, especially when building traditional, non-multilingual sites, it has been re-introduced in version 8.1 as document.GetCultureFromDomains().

CHANGE: None.

DomainHelper

DomainHelper has been replaced with a static DomainUtilities class.

CHANGE: It is rare that DomainHelper is used in code since it only contains one public method but if developers are using this, it can no longer be injected since it's now a static class called DomainUtilities.

Models Builder

If you're using ModelsBuilder in dll mode you need to delete the dlls before upgrading. Otherwise, they're going to be wrong and cause your whole site to throw errors.

If you're using ModelsBuilder in AppData mode and you have your generated models in your solution you need to update them after upgrading. PublishedContentType will need to be replaced with IPublishedContentType. If you have an implementation of the PropertyValueConverter class, you need to replace all references to PublishedPropertyType with IPublishedPropertyType within that class. Only after you do that will your solution build again.

AutoMapper

7.latest to 8.0.0

There is no direct upgrade path from Umbraco 7 to Umbraco 8. It is however possible to migrate content from Umbraco 7 sites to Umbraco 8 sites. We have added content migrations in Umbraco 8.1.0 enabling you to migrate your content from Umbraco 7 to Umbraco 8.

It is not possible to upgrade an Umbraco 7 site to Umbraco 8 because the codebase has been fundamentally updated in Umbraco 8. A lot of outdated code and technology has been removed and instead new, faster, and more secure technology has been implemented.

In Umbraco 8 we have added improvements and updated dependencies. We have also done a thorough clean-up to make it simpler for you to work with and extend your Umbraco project.

7.6.3 to 7.7.0

Version 7.7.0 introduces User Groups, better user management, and security facilities. This means that anything to do with "User Types" no longer exists including APIs that work with User Types. If your code or any package's code refers to "User Type" APIs, you need to make changes to your code. In many cases, we've added backward compatibility for these scenarios and obsoleted APIs that should no longer be used.

We are now by default using the e-mail address and not the username for the credentials. When trying to login to the backoffice you need to use the e-mail address as opposed to the username. If you do an upgrade from an older version and would like to keep using the username, change the <usernameIsEmail>true</usernameIsEmail> setting to false.

Version 7.7.2 no longer ships with the CookComputing.XmlRpcV2 assembly. If you reference this assembly or have a package that requires this assembly, you need to copy it back into your website.

This version also ships with far fewer client files that were only relevant for older versions of Umbraco (i.e. < 7.0.0). There might be some packages that were referencing these old client files. If you see missing image references you may need to contact the vendor of the package in question to update their references.

7.6.0 to 7.6.3

In short:

In Umbraco version 7.6.2 we made a mistake in the Property Value Converts (PVCs). This was corrected 2 days later in version 7.6.3. If you were having problems with querying the following Data Types on the frontend, make sure to upgrade to 7.6.3:

Multi Node Tree Picker
Related Links
Member Picker

Depending on whether you tried to fix the problem with those, you will need to fix them after you upgrade to 7.6.3.

Property Value Converters (PVC)

Umbraco stores data for Data Types in different ways. For a lot of pickers it will store 1072 or 1083,1283. These numbers refer to the identifier of the item in Umbraco. In the past, when building your templates, you would manually have to take that value and find the content item it belongs to. Then you would be able to get the data you wanted from there. An example of that is shown below:

In Umbraco 7.6.0, this is what you would do instead:

To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.

We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (<EnablePropertyValueConverters>false</EnablePropertyValueConverters>).

To make everything consistent, we made sure that the UDI pickers would always use PVC's in 7.6.2, this however reversed the behavior. So when PVC's were enabled, the property would not be converted and when PVC's were disabled, the property would be converted after all. This is the exact opposite behavior of 7.6.2.

So we have fixed this now in 7.6.3.

This issue only affects:

Multi Node Tree Picker
Related Links
Member Picker

Have you already upgraded to 7.6.2 and fixed queries for those three Data Types? Then you have to do that again in version 7.6.3.

7.4.0 to 7.6.0

The three most important things to note are:

In web.config do not change useLegacyEncoding to false if it is currently set to true - changing the password encoding will cause you not being able to log in any more.
In umbracoSettings.config leave EnablePropertyValueConverters set to false - this will help your existing content queries to still work.
In tinyMceConfig.config make sure to remove <plugin loadOnFrontend="true">umbracolink</plugin> so that the rich text editor works as it should.

Breaking Changes

Dependencies

Umbraco has used a custom build of an old (1.2.11) version of log4net that supported Medium Trust. However, Umbraco itself does not support Medium Trust anymore, and therefore log4net has been upgraded to the standard, latest build of log4net 2.0.8.

An optional parameter has been added to the GetCropUrl method in order to support the background color parameter. This breaks the method signature and therefore might require a recompile of user's code.

The HtmlAgilityPack has been upgraded to version 1.4.9.5. The Umbraco upgrade process should take care of setting up the binding redirects appropriately.

Core

The Membership Provider useLegacyEncoding setting is now false by default, as the legacy password encoding has weaknesses.

This change only impacts new installs (no change for upgrades).

A large amount of property value converters contributed by the community have been merged in and are now the default value converters. These converters change the object types returned by GetPropertyValue for more convenient types.

Instead of returning comma-separated string values like it did before, the SliderValueConverter now returns a decimal or a Range<decimal> value that can be used directly in views.

This change only impacts new installs (no change for upgrades).

The new property value converters are controlled by an umbracoSettings.config setting. In the section settings/content, setting EnablePropertyValueConverters needs to be present and true to activate them.

Umbraco has been using a PetaPoco-managed UmbracoDatabase instance since version 7 came out. We realized that some of our legacy code still bypassed that mechanism and used parallel, out-of-band database connections, causing issues with transactions.

The legacy code has been refactored to rely on the UmbracoDatabase instance. However, because that database is disposed of during EndRequest, the code that ran after it has been disposed may not work anymore. This should then be updated to use either an HttpModule event that occurs before EndRequest or the new UmbracoModule.EndRequest event.

Version 7.6 introduces the notion of scopes, which allow for wrapping multiple service-level operations in one single transaction. The scopes API is partially public. Scopes are not meant for public use at this stage and we need a few more releases to ensure that the APIs are stable.

Scopes should not change how Umbraco functions.

The property editors for pickers for content, media, members, and related links have been updated to store UDI instead of the node ID. Pickers in sites being upgraded have been marked as obsolete but will continue to work as they always did.

New sites will have the obsolete pickers filtered out from the list of available property editors, but they can be enabled by a configuration flag.

For a long time, we had a rel attribute on an <img> tag when inserted into the RTE. This is invalid HTML markup. We worked around this by stripping this attribute using a Property Editor Value converter. Some developers relied on this attribute so we didn't change it to a "data-id" attribute which would have been valid. In 7.6 we are not storing integer IDs in these attributes. Instead of storing UDI values so with this change we no longer use rel or data-id and instead there will be a "data-udi" attribute. This change should affect only a small amount of people that were previously relying on the values from the "rel" attribute.

Others

We are shipping with SignalR in the core at version 2.2.1. If you already have SignalR installed into your app and are using an older version there may be conflicts.

The creation and editing of WebForms templates will no longer be supported as for version 7.6.0.

Upgrading via NuGet

This is an important one and there was no perfect solution to this. We have removed the UrlRewriting dependency and no longer ship with it. However, if you are using it we didn't want to have NuGet delete all of your rewrites. The good news is that if you are using it, the NuGet upgrade will not delete your rewrite file and everything should continue to work.

However, if you are not using it, you will get an error after upgrading. Here's how to fix it:

Since you aren't using UrlRewriting you will have probably never edited the UrlRewriting file. In this case, NuGet will detect that and remove it. However you will need to manually remove these UrlRewriting references from your web.config:

and

Remove the following httpModules from your web.config:

and

Forms

Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0

Courier

Umbraco Courier 3.1.0 has been released to be compatible with Umbraco 7.6. If you are using Courier, you will need to update it to version 3.1.0.

7.3.0 to 7.4.0

For manual upgrades:

Copy the new folder ~/App_Plugins/ModelsBuilder into the site
Do not forget to merge ~/Config/trees.config and ~/Config/Dashboard.config - they contain new and updated entries that are required to be there
- If you forget trees.config you will either not be able to browse the Developer section or you will be logged out immediately when trying to go to the developer section

7.2.0 to 7.3.0

Make sure to manually clear your cookies after updating all the files, otherwise you might an error relating to Umbraco.Core.Security.UmbracoBackOfficeIdentity.AddUserDataClaims(). The error looks like: Value cannot be null. Parameter name: value.

NuGet will do the following for you. If you're upgrading manually make sure to also:

Delete bin/Microsoft.Web.Helpers.dll
Delete bin/Microsoft.Web.Mvc.FixedDisplayModes.dll
Delete bin/System.Net.Http.dll
Delete bin/System.Net.Http.*.dll (all dll files starting with System.Net.Http) except for System.Net.Http.Formatting.dll
Delete bin/umbraco.XmlSerializers.dll
Add this in the appSetting section of your web.config file: <add key="owin:appStartup" value="UmbracoDefaultOwinStartup" />

Other considerations:

WebApi has been updated, normally you don’t have to do anything unless you have custom webapi configuration:
- You need to update your web.config file to have the correct WebApi version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
MVC has been updated to MVC5
- You need to update your web.config file to have the correct MVC version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
- The upgrader will take care of updating all other web.config’s (in all other folders, for example, the Views and App_Plugins folders) to have the correct settings
It is not required that you merge the changes for the Examine index paths in the ExamineIndex.config file. However, if you do, your indexes will be rebuilt on startup because Examine will detect that they don’t exist at the new location.
It's highly recommended to clear the browser cache - the ClientDependency version is automatically bumped during installation which should force the browser cache to refresh, however in some edge cases this might not be enough.

7.1.0 to 7.2.0

Copy in the /Views/Partials/Grid (contains Grid rendering views).

7.0.2 to 7.1.0

Remove the /Install folder.

7.0.1 to 7.0.2

There was an update to the /umbraco/config/create/ui.xml which needs to be manually updated. The original element had this text:

The usercontrol value has changed to: /create/user.ascx. This is a required change otherwise creating a new user will not work.

7.0.0 to 7.0.1

Remove all uGoLive dlls from /bin
- These are not compatible with V7
Move appSettings/connectionStrings back to web.config
- If you are on 7.0.0 you should migrate these settings into the web.config instead of having them in separate files in /config/
- The keys in config/AppSettings.config need to be moved back to the web.config <appSettings> section and similarly, the config/ConnectionStrings.config holds the Umbraco database connections in v7.0.0 and they should be moved back to the web.config <connectionStrings> section.
- /config/AppSettings.config and /config/ConnectionString.config can be removed after the contents have been moved back to web.config.
Delete all files in ~/App_Data/TEMP/Razor/
- Related to issues with razor macros

6.latest to 7

4.latest to 6

The DocType Mixins package is not compatible with v6+ and will cause problems in your Document Types.

Version 4

Version 4.10.x to 4.11.x

Version 4.8.0 to 4.10.0

Delete the bin/umbraco.linq.core.dll file
Copy the new files and folders from the zip file into your site's folder
- /App_Plugins
- /Views
- Global.asax
Remove the Config/formHandlers.config file

Version 4.7.2 to 4.8.0

Delete the bin/App_Browsers.dll file
Delete the bin/App_global.asax.dll file
Delete the bin/Fizzler.Systems.HtmlAgilityPack.dll file

Version 4.7.1.1 to 4.7.2

Delete the bin/umbraco.MacroEngines.Legacy.dll file

Version 4.6.1 to 4.7.1.1

Delete bin/Iron*.dll (all dll files starting with "Iron")
Delete bin/RazorEngine*.dll (all dll files starting with "RazorEngine")
Delete bin/umbraco.MacroEngines.Legacy.dll
Delete bin/Microsoft.Scripting.Debugging.dll
Delete bin/Microsoft.Dynamic.dll

Upgrade from Umbraco 8 to the latest version

Learn how to upgrade your Umbraco 8 project to Umbraco 10.

It is currently not possible to upgrade directly from Umbraco 8 to the latest version.

The recommended approach for upgrading from version 8 to the latest version is to use this guide to upgrade from Umbraco 8 to Umbraco 10. Umbraco 10 contains the database migrations that must be upgraded from Umbraco 8. You can then use the Upgrading to Major steps to upgrade from Umbraco 10 to the latest version.

Since the underlying framework going from Umbraco 8 to the latest version has changed, there is no direct upgrade path. That said, it is possible to re-use the database from your Umbraco 8 project on your new project in order to maintain the content.

It is not possible to migrate the custom code as the underlying web framework has been updated from ASP.NET to ASP.NET Core. All templates and custom code will need to be reimplemented.

You also need to make sure that the packages you are using are available on the latest version.

Prerequisites

A Umbraco 8 project running the latest version of Umbraco 8.
A backup of your Umbraco 8 project database.
A clean installation of the latest version of Umbraco.

If you use Umbraco Forms, then on the clean installation of Umbraco, you will need to install Umbraco.Forms package as well.

Video Tutorial

The video below shows how to complete the upgrade on an Umbraco Cloud project. Most of the process is the same, however, the video does contain some Cloud-specific elements.

Step 1: Content Migration

If you use Umbraco Forms, make sure to have StoreUmbracoFormsInDbsetto True before step 1.

Create a backup of the database from your Umbraco 8 project (after you have upgraded to the latest version of v8). For this, you can use the database backup guide.
Import the database backup into SQL Server Management Studio.
Update the connection string in the new projects appsettings.json file so that it connects to the Umbraco 8 database:

"ConnectionStrings": {
    "umbracoDbDSN": "Server=YourLocalSQLServerHere;Database=NameOfYourDatabaseHere;User Id=NameOfYourUserHere;Password=YourPasswordHere;TrustServerCertificate=True"
}

You can also add the connection details if you spin up a clean installation.

Run the new project and login to authorize the upgrade.
Select "Upgrade" when the upgrade wizard appears.
Once the upgrade has been completed, it's recommended to login to the backoffice to verify if your project is upgraded to new version.

This is only content migration and the database will be migrated.

You need to manually update the view files and custom code implementation. For more information, see Step 3 of this guide.

Step 2: File Migration

The following files/folders need to be copied from the Umbraco 8 project into the new project:
- ~/Views - Do not overwrite the default Macro and Partial View Macro files unless changes have been made to these.
- ~/Media - Media folder from v8 needs to be copied over into the wwwroot - media folder
- Any files/folders related to Stylesheets and JavaScript.
Migrate custom configuration from the Umbraco 8 configuration files (.config) into the appsettings.json file on the new project.
- As of Umbraco version 9, the configuration no longer lives in the Web.Config file and has been replaced by the appsettings.json file. Learn more about this in the Configuration article.
Migrate Umbraco Forms data to the database, if relevant.
- As of Umbraco Forms version 9, it is only possible to store Forms data in the database. If Umbraco Forms was used on the Umbraco 8 project, the files need to be migrated to the database.
Run the new project.
- It will give you an error screen on the frontend as none of the Template files have been updated. Follow Step 3 to resolve the errors.

Step 3: Custom Code in the latest version

The latest version of Umbraco is different from Umbraco 8 in many ways. With all the files and data migrated it is now time to rewrite and re-implement all custom code and templates.

Examples of changes

One of the changes is how published content is rendered through Template files. Due to this, it will be necessary to update all the Template files (.cshtml) to reflect these changes.

Read more about these changes in the IPublishedContent section of the Umbraco CMS documentation.

Template files need to inherit from Umbraco.Cms.Web.Common.Views.UmbracoViewPage<ContentModels.HomePage> instead of Umbraco.Web.Mvc.UmbracoViewPage<ContentModels.HomePage>
Template files need to use ContentModels = Umbraco.Cms.Web.Common.PublishedModels instead of ContentModels = Umbraco.Web.PublishedModels

For more information on the correct namespaces or custom code, you can find the references in the API Documentation article.

Depending on the extent of the project and the amount of custom code and implementations, this step is going to require a lot of work.

Once the new project runs without errors on a local setup it is time to deploy the website to production.

This concludes this tutorial. Find related information and further reading in the section below.

Migrate content to Umbraco 8

This guide will show you how to migrate the content from your Umbraco 7 site to a site running Umbraco 8.

Umbraco 8 contains a lot of breaking changes and a lot of code has been cleaned up compared to Umbraco 7. Due to this, it will not be possible to do a direct upgrade from Umbraco 7 to Umbraco 8. You need to migrate your content from your Umbraco 7 site into your Umbraco 8 site and then recreate the rest in the new version.

A content migration tool has been implemented in Umbraco 8.1.0, to help you with the transition.

In this guide you can read more about the tool, its limitations, and how to use it in practice.

Migrating Umbraco Cloud sites

Follow the steps outlined in the Umbraco Cloud documentation to upgrade your Umbraco 7 site on Cloud.

What are the limitations?

In the following section, you can learn more about the limitations of migrating content from Umbraco 7 to Umbraco 8.

Versions supported

The content migration tool is a database migration, which is made for the database schema of Umbraco 7.14+. This means that in order to do the migration you need to ensure your Umbraco 7 site is running at least Umbraco 7.14.

Database types supported

Umbraco 8 does not support MySQL databases. This means that the migration will not work when moving from an Umbraco 7 site using MySQL to Umbraco 8 on SQL Server

The database types that are supported are SQL Server and SQL CE.

Known issues

Feedback from user testing has shown that some databases are harder to migrate than others.

We are collecting a list of these known issues on our GitHub Issue Tracker. There is a community package: Pre-migration health checks that you can install on your Umbraco 7 site before migration. This will help identify and resolve some of these common issues before triggering the migration steps detailed below.

A migration was introduced in Umbraco 8.6 which can break the migration process. See Issue #7914 for more details.

There are two ways to work around this issue:

Migrate to version 8.5 as a first step and then post-migration, carry out a normal Umbraco upgrade to the latest version of Umbraco 8, or
Install the following community Nuget Package: ProWorks Umbraco 8 Migrations into your Umbraco 8 project before running the migration (no configuration required). This package was created by Umbraco Gold Partner ProWorks and patches the migration process so you can migrate directly from the latest Umbraco 7 to Umbraco 8.6+ without encountering the above issue. Learn more about the package and the migration process on Prowork's blog.

Third party property editors

The migration will transform the data stored in third party editors as well. However, it will be stored as it was in Umbraco 7. If the structure has changed or the property editor doesn't exist, you will still be able to find the data in the database. It will, however, not be available in the backoffice.

Learn more about that in the Data Types Migrations

Migrating data types

When migrating content from Umbraco 7 to Umbraco 8, the Data Type 'pre-value' structure has changed. In Umbraco 8, the term 'pre-values' no longer exists and is instead referred to as property editor configuration.

In Umbraco 8, property editor configuration is a strongly typed object. There are plenty of examples in the Umbraco-CMS codebase.

This configuration is stored differently in Umbraco 8 than it was in Umbraco 7. In Umbraco 7, each pre-value property was stored as a different row in a different database table. In Umbraco 8 this is simplified and property editor configuration is stored as the JSON serialized version of the strongly typed configuration object.

When upgrading from Umbraco 7 to Umbraco 8, Umbraco has no way of knowing how custom property editors have intended to structure their configuration data. During the upgrade, Umbraco will convert the key/value pairs from the old pre-value database table into a serialized JSON version of those values. There is a reasonable chance that the end result of this data conversion is not compatible with the custom property editor.

There are 3 options that a developer can choose to do to work around this automatic data conversion:

1: Implement a custom IPreValueMigrator

This option requires you to create a custom C# migrator for each of your custom property editors that store custom configuration data. It will also require that you implement these migrators before you run the Umbraco 8 content migration.

To do this, you will create an implementation of IPreValueMigrator or inherit from the base class DefaultPreValueMigrator.

There are plenty of examples of this in the Umbraco-CMS codebase.

You will then need to register them in a composer:

[RuntimeLevel(MinLevel = RuntimeLevel.Upgrade, MaxLevel = RuntimeLevel.Upgrade)] // only on upgrades
public class PreValueMigratorComposer : IUserComposer
{
    public void Compose(Composition composition)
    {
        composition.WithCollectionBuilder<PreValueMigratorCollectionBuilder>()
            // Append all of the migrators required
            .Append<MyCustomPreValueMigrator>()
            .Append<AnotherPreValueMigrator>();
    }
}

When running the migrations and encountering a custom configuration, Umbraco will utilize the PreValueMigrator when converting the old pre-values into the new JSON format.

2: Update your Angular configuration (pre-value) and property editor

This option means that you will choose to use the automatically converted JSON data format. In this case, it will mean updating your pre-value and property editors to use the new JSON configuration data. The converted data won't be much different than the original/intended data format so this might not be too much work.

3: Update the Angular configuration (pre-value) editor

With this option the configuration/pre-value editor needs to be updated to transform the JSON converted data into the data structure you want. When this is done and when the Data Type is saved again, the JSON data structure will be saved back to the database. Your property editor will then continue to work.

This will require you to update and save all custom pre-value editors to transform the converted structures back to your intended data structure.

What will happen

When the migrations are running, Umbraco will go through your entire Umbraco 7 database and update it to the format required for Umbraco 8. The schema will be remodeled and transformed into the correct format and your existing compatible data will be transformed to fit with Umbraco 8.

These migrations will be running directly on your database. They are transforming schema and data - not transferring. Therefore always ensure that you have a backup before attempting to do this. In case something goes wrong, you will be able to rollback and try again.

It is highly recommended to clean up your site before running this as it will be quicker.

Empty Content recycle bin
Empty Media recycle bin
Clean up the database version history (can be done with a script or a package like Unversion)

How it works

In the following guide we will migrate the content of an Umbraco 7.13.1 site to Umbraco 8.1.0.

Step 1: Upgrading to 7.14+

Before the content migration can start the site has to run Umbraco 7.14+. Make sure to always take a backup of the database before doing an upgrade, and then check the version specific upgrade instructions.

The site in this example is an Umbraco 7.13.1 site, and we will use Nuget to update it.

Following the general upgrade instructions we will now upgrade via Nuget until we get to this point:

When upgrading an old website, check if you are using obsolete properties in your Data Types. These should be changed to their updated counterparts. The migration will fail if you are still using obsolete properties.

The updated properties are:

Content Picker
Media Picker
Member Picker
Multinode Treepicker
Folder Browser
Related Links

You can see if your site is using the obsolete properties from the (Obsolete) prefix in their name.

Install the Pre-migration health checks plugin, and run it health check from the Developer section of the backoffice. This is done to identify and resolve some common database schema issues before migration.

Once it is upgraded and you have verified everything is working, move on to the next step.

Step 2: Migrating content to Umbraco 8

The first thing to do is to spin up a fresh new Umbraco 8.1+ site. Make sure everything works and that no content is there.

If you have customized the UsersMembershipProvider on your Umbraco 7 site you need to copy that over to the 8.1 web.config as well. Additionally you need to update the type attribute to be type="Umbraco.Web.Security.Providers.UsersMembershipProvider, Umbraco.Web".

This also includes the attribute useLegacyEncoding value. Make sure that this setting is copied into your new Umbraco 8 site, as it is needed in order to log in.

Take a backup of your database from the Umbraco 7.14 site. Take the information for the backup database and add that to the connectionstring for the Umbraco 8.1 site. If you are running SQL CE, you will have to copy the database over to the new site as well.

Once the connectionstring is set, the final step is to change the Umbraco version number in the web.config on the Umbraco 8.1 site. Chang it to 7.14.0. This will indicate that there is an upgrade pending and it needs to run the migration.

The version will be set to 8.1.0, and you need to change it to the version you are currently migrating from.

When you start the site it will ask you to login and then show you this screen:

From here, the automatic migration will take over, and after a little bit you can log in and see your content:

Please be aware that this is a content migration. If you go to the frontend after following these steps, it will throw errors.

At this point you will have the content but nothing else.

Step 3: Files migration

Before moving on to this step, make sure that the Umbraco 8 project is no longer running.

The following files/folders need to be copied into the Umbraco 8 project:

~/Views - do not overwrite the default Macro and Partial View Macro files, unless changes have been made to these.
~/Media
Any files/folders related to Stylesheets and JavaScripts.
Any custom files/folders the Umbraco 7 project uses, that aren't in the ~/Config or ~/bin.
~/App_Data/UmbracoForms - in the case Umbraco Forms was used on the Umbraco 7 site.

Merge the configuration files carefully to ensure any custom settings are migrated while none of the default configurations for Umbraco 8 is overwritten.

You'll have to revisit all templates and custom implementations to get the site up and running, as all markup is still Umbraco 7-specific.

Are you planning on continuing the migration to the latest version on Umbraco CMS?

Then you can skip the step to revisit the template files and custom implementation. We highly recommend waiting with this step until you've reached the latest version.

If you're stopping at Umbraco 8, you can learn more about rendering content on the Legacy Docs site.

Step 4: Post-migration checks

As you are updating your template files and custom implementation, you should also verify your configuration files and settings.

Umbraco 8 contains a few changes regarding the Sections in the Umbraco Backoffice. Because of this, you should also check your User Groups and make sure they have access to the appropriate sections.

Learn more about the Section in the Sections article

Minor upgrades for Umbraco 8

This article provides details on how to upgrade to the next minor version when using Umbraco 8.

Sometimes there are exceptions to these guidelines, which are listed in the version-specific guide.

Note

It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site you need to repeat the steps below. Make sure you click through the install screens so that your upgrade is complete.

In this article you will find instructions for 3 different ways of upgrading:

Upgrade using NuGet
Upgrade manually from a Zip file
Run an unattended upgrade (v8.12+)

Upgrade using NuGet

Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
- If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the version-specific guide.

Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:

Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.

The upgrade will run through all the files and make sure you have the latest changes while leaving files you have updated.

Upgrade manually from a zip file

Download the .zip file for the new version you are upgrading to from https://our.umbraco.com/download

Copy the following folders from inside the .zip file over the existing folders in your site:

/bin
/Umbraco

There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Normally on Windows this is not a problem. If your hosting provider however forces proper casing, you will need to verify that the folder and file names are in the same casing as in the newest version you're upgrading to.

Merge configuration files

You can expect some changes to the following configuration files:

Any file in the /Config folder
The /Global.asax file
The web.config file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config file in the /Views folder

Use a tool like WinMerge to check changes between all of the config files. Depending on when you last did this there may have been updates to few of them.

There's also the possibility that some files in the /Config folder are new or some have been removed (we do make a note of this in the release notes). WinMerge (and other diff tools) can compare folders as well so you can spot these differences.

Merge UI.xml and language files

Some packages like Umbraco Forms add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.

Packages like Umbraco Forms and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).

Finalize

After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.

The installer will do two things:

Update the version number in the web.config
Upgrade your database in case there are any changes

We are aware that, currently, the installer is asking you for the database details of a blank database while upgrading. In the near future this will be pre-filled with your existing details and the wording will be updated. So no need to be scared. Enter the details of your existing database and Umbraco will upgrade it to the latest version when necessary.

Run an unattended upgrade

When upgrading your Umbraco project to Umbraco v8.12+ it is possible to enable the upgrade to run unattended. This means that you will not need to run through the installation wizard when upgrading.

Below you will find the steps you need to take in order to upgrade your project unattended.

Are you running a load balanced setup with multiple servers and environments?

Check out the section about Unattended upgrades in a load balanced setup.

Enable the feature

Add the Umbraco.Core.RuntimeState.UpgradeUnattended key to appSettings in your web.config file.
Set the value of the key to true.

    <add key="Umbraco.Core.RuntimeState.UpgradeUnattended" value="true" />

Check the `ConfigurationStatus`

In order to trigger the actual upgrade, the correct version number needs to be set.

It is important to use the version number of the version that you are upgrading to. If this is not set, the upgrade will not run even if the UpgradeUnattended key has been set to true.

Locate the ConfigurationStatus key in the appSettings section in your web.config file.
Update the value to match the Umbraco version that you are upgrading to.

<add key="Umbraco.Core.ConfigurationStatus" value="x.x.x"/>

Run the upgrade

With the correct configuration applied, the project will be upgraded on the next boot.

While the upgrade processes are running, any requests made to the site will be "put on hold", meaning that no content will be returned before the upgrade is complete.

Boot order

The Runtime level will use Run instead of Upgrade in order to allow the website to continue to boot up directly after the migration is run, instead of initiating the otherwise required restart.

The upgrade is run after Composers but before Components. This is because the migration requires services that are registered in Composers and Components requires that Umbraco and the database is ready.

Unattended upgrades in a load balanced setup

Follow the steps outlined below to use run unattended upgrades in a load balanced setup.

Upgrade Umbraco via NuGet in Visual Studio. Make sure the Umbraco.Core.ConfigurationStatus key in appSetting in the web.config file is updated to match the target version.
Deploy to all environments, including the updated appSetting for Umbraco.Core.ConfigurationStatus.
Set the Umbraco.Core.RuntimeState.UpgradeUnattended key in appSetting in the web.config to true for the Main server only.
Request a page on the Main server and the upgrade will run automatically.
Wait for the upgrade to complete.
Browse the Read-Only servers and make sure they do not show the “upgrade required” screen.

Post installation

One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.

Potential issues and gotchas

Browser cache

Google Chrome has notoriously aggressive caching, so if something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you however wish to re-force this update you can increment this version number which will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.

One way to nudge the cache in Chrome is to open the developer tools (F12) and go to the settings (the cog icon). There will be a checkbox that says "Disable cache (while DevTools is open)". Once this checkbox is on you can refresh the page and the cache should be invalidated. To force it even more, the "reload" button next to your address bar now has extra options when you right-click it. It should have "Normal reload", "Hard reload" and "Empty cache and hard reload" now. The last option is the most thorough and you might want to try that.

Upgrade to Umbraco 7

This document should be used as a reference, not a step by step guide. Upgrading will largely depend on what version of Umbraco you are currently running, what packages you have installed and the many

The still apply to this process as well.

Backup

It is critical that you back up your website and database before upgrading. There are database changes made during installation and you cannot revert an Umbraco 7 database to an Umbraco 6 database.

.Net 4.5

Umbraco 7 is built on .Net 4.5 and your development environment will require this version installed in order to operate. Visual Studio users may require 2012 or higher.

HTML 5 browser support

Umbraco 7 requires browsers with proper HTML 5 support, these include Chrome, Firefox, IE10+

Breaking changes

Before you upgrade be sure to read the list of breaking changes. This is especially recommended if you have removed or modified code in the core or if one of these breaking changes directly affects your installation.

for more details.

Examine

It is recommended to rebuild all Examine indexes after completing the upgrade.

Xml Cache rebuild

You should re-generate the XML cache. This can be done by following the prompts when visiting the following URL:

your-domain.com/umbraco/dialogs/republish.aspx?xml=true

Configuration changes

It is recommended that you use a Diff tool to compare the configuration file changes with your own current configuration files.

/web.config updates
- You will need to compare the new Umbraco 7 web.config with your current web.config. Here is a quick reference of what needs to change:
  - Remove the section name="BaseRestExtensions" section
  - Remove the section name="FileSystemProviders" section
  - Remove the sectionGroup name="system.web.webPages.razor" section
  - Remove the <FileSystemProviders> element
  - Remove the BaseRestExtensions element
  - Remove the add key="umbracoUseMediumTrust" element
  - Remove the system.web.extensions element
  - Removes the xhtmlConformance element
  - Remove the system.codedom element
  - Remove the compilation assemblies, /compilation
  - Remove the system.web.webPages.razor element
  - New: sectionGroup name="umbracoConfiguration" section
  - New: umbracoConfiguration element
  - Ensure that the targetFramework="4.5" is added to the httpRuntime element
  - Add add key="ValidationSettings:UnobtrusiveValidationMode" value="None" to the appSettings element
/config/clientdependency.config changes
- remove add name="CanvasProvider" element
/views/web.config updates
New macroscripts/web.config
config/umbracoSettings.config
- Remove the EnableCanvasEditing element
- Remove the webservices element
Removed xsltExtensions.config
/config/applications.config and /config/trees.config have some icon paths and names updated. You need to merge the new changes into your existing config files.
/config/tinyMceConfig.config
- The inlinepopups is compatible and supported in Umbraco 7. You need to remove these elements: plugin loadOnFrontend="true", inlinepopups/plugin;
- The plugins element that is shipped with Umbraco 7 looks like this:
  - You need to merge the changes from the new tinyMceConfig file into yours. The command elements that have changed are: JustifyCenter, JustifyLeft, JustifyRight, JustifyFull, umbracomacro, umbracoembed, mceImage, subscript, superscript, styleselect
  - Remove the command: mceSpellCheck
/config/dashboard.config
- You need to merge the changes from the new dashboard.config into yours. Some of the original dashboard entries that were shipped with Umbraco 6 have been replaced or removed.

Medium Trust

Umbraco 7+ will no longer support medium trust environments. There are now some assemblies used in the core that do not support medium trust but are used extensively. Plugin scanning now also allows for scanning Umbraco's internal types which requires full trust.

Events

Tree events

Content, Media, Members, and Data Type trees will no longer raise the legacy tree events (based on BaseTree). It is recommended to change all tree event handlers to use the new tree events that fire for every tree in Umbraco including legacy trees. The new tree events are static events and are found in the class Umbraco.Web.Trees.TreeControllerBase:

MenuRendering
RootNodeRendering
TreeNodesRendering

Legacy business logic events

The Content, Media, Member, and Data Type editors have been re-created and are solely using the new Umbraco Services data layer. This means that operations performed in the backoffice will no longer raise the legacy business logic events (for example, events based on umbraco.cms.businesslogic.web.Document). It is recommended to change your event handlers to subscribe to the new Services data layer events. These are static events and are found in the services. For example: Umbraco.Core.Services.ContentService.Saved.

Property Editors

Legacy property editors (pre-Umbraco 7) will not work with Umbraco 7. During the upgrade installation process, Umbraco will generate a report showing you which legacy property editors are installed. These will all be converted to a readonly Label property editor. No data loss will occur but you'll need to re-assign your existing data types to use a new compatible Umbraco 7 property editor.

Most Umbraco core property editors shipped will be mapped to their equivalent Umbraco 7 editors. The Image cropper editor has not been completed for v7.0.

Since the Related Links property is an advanced property editor, the data format has changed from XML to JSON. This should not have any effect when retrieving the data from razor. If you are outputting Related Links data with XSLT you will need to update your XSLT snippet. Making use of the new library method umbraco.library:JsonToXml and taking into account that the xml structure has also slightly changed.

GUID -> Alias mapping

One of the database changes made in Umbraco 7 is the change of referencing a property editor from a GUID to a string alias. In order to map a legacy property editor to a new Umbraco 7 version you can add your custom "GUID -> Alias" map during application startup. To do this you would add your map using this method: Umbraco.Core.PropertyEditors.LegacyPropertyEditorIdToAliasConverter.CreateMap

Parameter Editors

Legacy parameter editors (pre-Umbraco 7) will not work with Umbraco 7. If Umbraco detects legacy parameter editor aliases that do not map to a Umbraco 7 parameter editor it will render a textbox in its place. You will need to update your macros to use a compatible Umbraco 7 parameter editor as those that aren't supported.

Previously, parameter editors were registered in an Umbraco database table: cmsMacroPropertyType which no longer exists. Parameter editors in Umbraco 7 are plugins like property editors. During the Umbraco 7 upgrade installation process it will update the new cmsMacroProperty.editorAlias column with the previous parameter editor alias. During this process it will look into the Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter for a map between a legacy alias to a new Umbraco 7 alias.

Custom legacy parameters can be mapped to new Umbraco 7 parameter editor aliases during installation. This can be done by modifying the mapping during application startup using this method: Umbraco.Core.PropertyEditors.LegacyParameterEditorAliasConverter.CreateMap.

Database changes

All database changes will be taken care of during the upgrade installation process.

For database change details see (including all child tasks):

Packages

You should check with the package creator for all installed packages to ensure they are compatible with Umbraco 7.

For package developers

We see common errors that we cannot fix for you, but we do have recommendations you can follow to fix them:

TypeFinder

The TypeFinder has been deprecated since 4.10 and is now found under Umbraco.Core.TypeFinder.

While you need to have JavaScript inside menu actions to trigger a response, it is highly recommended that you use the recommended UmbClientMgr methods. You should not try to override parent.right.document and similar tricks to get to the right-hand frame.

Use the recommended Umbraco uicontrols

If you have a webforms page, it is recommended to use the built-in ASP.NET controls to render panels, properties and so on. If you use the raw HTML or try to style it to match the backoffice, you will get out of sync. Follow the guidelines set by Umbraco's internal editors and use the ASP.NET custom controls for UI.

Minor upgrades for Umbraco 7

This article provides details on how to upgrade to the next minor version when using Umbraco 7.

Sometimes there are exceptions to these guidelines, which are listed in the version-specific guide.

Note

It is necessary to run the upgrade installer on each environment of your Umbraco site. If you want to update your staging and live site then you need to repeat the steps below and make sure that you click through the install screens to complete the upgrade.

In this article you will find instructions for 2 different ways of upgrading:

Upgrade using NuGet
Upgrade manually from a Zip file

Upgrade using NuGet

Open up the Package Console and type: Update-Package UmbracoCms
Choose "No to All" by pressing the "L" when prompted.
- If there are any specific configuration changes required for the version you are upgrading to then they will be noted in the version-specific guide.

Alternatively, you can use the Visual Studio NuGet Package Manager to upgrade:

Open the NuGet Package Manager and select the Updates pane to get a list of available updates.
Choose the package called UmbracoCms and select update.

The upgrade will run through all the files and make sure you have the latest changes while leaving the files you have updated.

Upgrades to versions lower than 7.2.0

If you're not upgrading to 7.2.0 or higher then you should follow these extra instructions. If you are upgrading to 7.2.0+ then you can skip this and go to Merge UI.xml and language.

You will be asked to overwrite your web.config file and the files in /config, make sure to answer No to those questions.

For some inexplicable reason, the installation will fail if you click "No to All" (in the GUI) or answer "L" (in the package manager console) to the question: "File 'Web.config' already exists in project 'MySite'. Do you want to overwrite it?" So make sure to only answer "No" (in the GUI) or "N" (in the package manager console).

We will overwrite the web.config file. We'll back it up so don't worry. You can find the backup in App_Data\NuGetBackup\20140320-165450\. The 20140320-165450 bit is the date and time when the backup occurred, which varies. You can then merge your config files and make sure they're up to date.

Upgrade manually from a zip file

Download the .zip file for the new version you are upgrading to from https://our.umbraco.com/download

Copy the following folders from inside the .zip file over the existing folders in your site:

/bin
/Umbraco
/Umbraco_Client

There are hosting providers (we know of one: RackSpace Cloud) that require proper casing of file and folder names. Generally, on Windows, this is not a problem. Is your hosting provider forcing proper casing? You'll then need to verify that folders and files are named in the same casing as the version you're upgrading to.

Merge configuration files

You can expect some changes to the following configuration files:

Any file in the /Config folder
The /Global.asax file
The web.config file in the root of your site (Important: make sure to copy back the version number, and the connection string as they were.)
In rare cases, the web.config file in the Views folder

Use a tool like WinMerge to check changes between all of the config files. Depending on when you last did this there may have been updates to a few of them.

There's also the possibility that files in the /Config folder are new or have been removed(we note this in the release notes). WinMerge (and other diff tools) is able to compare folders as well so you can spot these differences.

Up until version 6.0.0 it was necessary to change the version number in ClientDependency.config. This was to clear the cached HTML/CSS/JS files in the backoffice. Change the current version number to one that's higher than that. Make sure not to skip this step as you might get strange behavior in the backoffice otherwise.

Merge UI.xml and language

Some packages (like Contour and Umbraco Forms) add dialogs to the UI.xml. Make sure to merge those changes back in from your backup during the upgrade so that the packages continue to work. This file can be found in: /Umbraco/Config/Create/UI.xml.

Packages like Contour, Umbraco Forms, and Courier also make changes to the language files located in: /Umbraco/Config/Lang/*.xml (typically en.xml).

Finalize

After copying the files and making the config changes, you can open your site. You should see the installer which will guide you through the upgrade.

The installer will do two things:

Update the version number in the web.config
Upgrade your database in case there are any changes

Post installation

One important recommendation is to always remove the install folder immediately after upgrading Umbraco and never to upload it to a live server.

Potential issues and gotchas

Browser cache

Google Chrome has notoriously aggressive caching. If something doesn't seem to work well in the backoffice, make sure to clear cache and cookies thoroughly (for other browsers as well). Normally the browser cache problem is automatically handled in an Umbraco upgrade by modifying the config/ClientDependency.config version number. If you wish to re-force this update you can increment this version number. This will ensure that any server-side cache of JavaScript and stylesheets gets cleared as well.

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 to complete the upgrade of your project.

Breaking changes

Umbraco 13

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

You can find more information about all breaking changes for v13.0.0 on website.

Note: 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.

Umbraco 12

Umbraco 12 does not include many binary breaking changes, but there are some.

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 .

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 .

The breaking changes in TinyMCE are also documented in the official migration guides for and from .

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 .

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.Cms.Core

Umbraco.Cms.Infrastructure

Umbraco.Cms.Web

Umbraco.Cms.Tests

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.Cms.Web

Umbraco.Cms.Infrastructure

New interface methods

A few interfaces have been merged, adding new members to the original interfaces.

Umbraco.Cms.Core

No-Operation methods removed

A method not doing anything for the last couple of major releases have been removed.

Umbraco.Cms.Core

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

Classes that does not inherit from base type anymore

The following classes now directly inherit from OEmbedProviderBase instead of EmbedProviderBase.

Umbraco.Cms.Core

Umbraco 10

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.

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 public methods: PublishedSnapshotServiceEventHandler.Dispose, PublishedSnapshotServiceEventHandler.Dispose(bool), and .PublishedSnapshotServiceEventHandler.Initialize.
Removed public ctor.

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.

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

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

umbracoMemberFailedPasswordAttempts
umbracoMemberApproved
umbracoMemberLockedOut
umbracoMemberLastLockoutDate
umbracoMemberLastLogin
umbracoMemberLastPasswordChangeDate

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.

Examine 3 breaking changes:

ValueSet immutable.
ValueSetValidationResult is renamed to ValueSetValidationStatus and ValueSetValidationResult is now a type.

Has changed to:

Added more methods to IRedirectUrlRepository and IRedirectUrlService.cs.

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.

Has changed to:

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

Release notes

You can find a list of all the released Umbraco versions on 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 instead, as it requires a few steps specific to Umbraco Cloud.

10.latest to the latest Umbraco version

It is recommended to upgrade to the closest version before upgrading to the latest version. For Umbraco 10, the closest long-term support version is Umbraco 13 so a direct upgrade is possible.

9.latest to 10

Watch the 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
Setup a new database for v10 and use to transfer document types and content across.
Setup a new database for v10 and use a premium tool such as to copy database contents across.
Setup a new database for v10 and use a premium tool such as 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.

Stop your site in IIS to prevent any changes being made to the database or filesystem while you are upgrading.
Open your Umbraco 9 project in Visual Studio.
Right-click on the project name in the Solution Explorer and select Properties.
Select .NET 6.0 from the Target Framework drop-down.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
Go to the Installed tab in the NuGet Package manager.
Choose Umbraco.Cms.
Select 10.0.0 from the Version drop-down and click Install to upgrade your project to version 10.
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>();
            });
}

Remove the following files and folders:
- /wwwroot/umbraco
- /umbraco/PartialViewMacros
- /umbraco/UmbracoBackOffice
- /umbraco/UmbracoInstall
- /umbraco/UmbracoWebsite
- /umbraco/config/lang
- /umbraco/config/appsettings-schema.json
If using Umbraco Forms, update your files and folders according to the for version 10 article.
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:

Ensure you have backups for both the database and the file system.
Stop the site so it is not accessible during the upgrade process.
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
If you are using Umbraco Forms, update your files and folders according to the for version 10 article.
Deploy the site how you normally would to your public facing environment.
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.
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 .

IPublishedContent breaking changes in 8.1.0

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

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.

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

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

The following IPublishedContent members change:

Name

CHANGE: Calls to document.GetCulture(culture).Name must be replaced with document.Name(culture).

UrlSegment

CHANGE: Calls to document.GetCulture(culture).UrlSegment must be replaced with document.UrlSegment(culture).

Culture

CHANGE: Calls to document.GetCulture(culture).Date must be replaced with document.CultureDate(culture). Calls to document.Cultures must take into account the invariant culture.

Children

A new document.ChildrenForAllCultures property is introduced, which returns all children, regardless of whether they are available for a culture or not.

Url

CHANGE: Calls to document.GetUrl(...) must be replaced with document.Url(...). Calls to document.UrlAbsolute() must be replaced with document.Url(mode: UrlMode.Absolute).

UmbracoContext

Due to the UrlProviderMode enumeration being renamed UrlMode, the signature of some overloads of the Url(...) method has changed. Methods that do not have a mode parameter remain unchanged.

CHANGE: Code such as context.Url(1234, UrlProviderMode.Absolute) must become context.Url(1234, UrlMode.Absolute).

GetCulture

Version 7 had a document.GetCulture() method that was deriving a culture from domains configured in the tree. Somehow, that method was lost during version 8 development (issue ).

Because that method is useful, especially when building traditional, non-multilingual sites, it has been re-introduced in version 8.1 as document.GetCultureFromDomains().

CHANGE: None.

DomainHelper

DomainHelper has been replaced with a static DomainUtilities class.

Models Builder

If you're using ModelsBuilder in dll mode you need to delete the dlls before upgrading. Otherwise, they're going to be wrong and cause your whole site to throw errors.

AutoMapper

Umbraco 8.1 replaces AutoMapper with . This in itself will not break anything on your site. If you have used AutoMapper in your own code you will have to either include the package yourself or switch your implementation to use UmbracoMapper.

Follow the to complete the upgrade

7.latest to 8.0.0

In Umbraco 8 we have added improvements and updated dependencies. We have also done a thorough clean-up to make it simpler for you to work with and extend your Umbraco project.

7.6.3 to 7.7.0

For a full list of breaking changes see:

Version 7.7.2 no longer ships with the CookComputing.XmlRpcV2 assembly. If you reference this assembly or have a package that requires this assembly, you need to copy it back into your website.

Follow the to complete the upgrade.

7.6.0 to 7.6.3

In short:

Multi Node Tree Picker
Related Links
Member Picker

Depending on whether you tried to fix the problem with those, you will need to fix them after you upgrade to 7.6.3.

Property Value Converters (PVC)

@{
    IPublishedContent contactPage;
    var contactPageId = Model.Content.GetPropertyValue<int>("contactPagePicker");
    if (contactPageId > 0)
    {
        contactPage = Umbraco.TypedContent(contactPageId);
    }
}

<p>
  <a href="@contactPage.Url">@contactPage.Name</a>
</p>

In Umbraco 7.6.0, this is what you would do instead:

<p>
    <a href="@Model.Content.ContactPagePicker.Url">@Model.ContactPagePicker.Name</a>
</p>

This is possible using Models Builder and through the inclusion of , a package by community member Jeavon Leopold.

To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.

Umbraco 7.6.0 also came with new pickers that store their data as a . We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.

We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (<EnablePropertyValueConverters>false</EnablePropertyValueConverters>).

So we have fixed this now in 7.6.3.

This issue only affects:

Multi Node Tree Picker
Related Links
Member Picker

Have you already upgraded to 7.6.2 and fixed queries for those three Data Types? Then you have to do that again in version 7.6.3.

Follow the to complete the upgrade.

7.4.0 to 7.6.0

Find a list of all the breaking changes below and

The three most important things to note are:

In web.config do not change useLegacyEncoding to false if it is currently set to true - changing the password encoding will cause you not being able to log in any more.
In umbracoSettings.config leave EnablePropertyValueConverters set to false - this will help your existing content queries to still work.
In tinyMceConfig.config make sure to remove <plugin loadOnFrontend="true">umbracolink</plugin> so that the rich text editor works as it should.

Breaking Changes

Dependencies

UrlRewriting.Net ()

UrlRewriting was old, leaking memory, and slowing down website startup when dealing with more than a few rules. It's entirely replaced by the extension.

Json.Net ()

Json.Net has been updated to version 10.0.0 to benefit from improvements in features, fixes, and performances (see ). This might be a breaking change for people relying on one of the changed functionality.

Log4net ()

ImageProcessor ()

HtmlAgilityPack ()

The HtmlAgilityPack has been upgraded to version 1.4.9.5. The Umbraco upgrade process should take care of setting up the binding redirects appropriately.

Core

Membership Provider Encoding ()

The Membership Provider useLegacyEncoding setting is now false by default, as the legacy password encoding has weaknesses.

This change only impacts new installs (no change for upgrades).

Property Value Converters ()

Instead of returning comma-separated string values like it did before, the SliderValueConverter now returns a decimal or a Range<decimal> value that can be used directly in views.

This change only impacts new installs (no change for upgrades).

Database ()

More details are available on on the 301 Redirect Tracker GitHub issue tracker.

Scopes ()

Scopes should not change how Umbraco functions.

Introducing scopes means that some public APIs signatures are changing. Most of these changes target internal and/or non-breaking APIs (as per our ). This should therefore have no impact on sites but may break unit tests.

Property Editors storing UDI instead of ID ()

New sites will have the obsolete pickers filtered out from the list of available property editors, but they can be enabled by a configuration flag.

Rich Text Editor (RTE) Images attributes (, )

Others

We are shipping with SignalR in the core at version 2.2.1. If you already have SignalR installed into your app and are using an older version there may be conflicts.

The creation and editing of WebForms templates will no longer be supported as for version 7.6.0.

Upgrading via NuGet

However, if you are not using it, you will get an error after upgrading. Here's how to fix it:

<section name="urlrewritingnet" restartOnExternalChanges="true" requirePermission="false" type="UrlRewritingNet.Configuration.UrlRewriteSection, UrlRewritingNet.UrlRewriter" />

and

<urlrewritingnet configSource="config\UrlRewriting.config" />

Remove the following httpModules from your web.config:

<system.web>
<httpModules>
    <add name="UrlRewriteModule" type="UrlRewritingNet.Web.UrlRewriteModule, UrlRewritingNet.UrlRewriter"/>
    ...
</httpModules>
<system.web>

and

<system.webServer>
    <modules>
    <remove name="UrlRewriteModule"/>
    <add name="UrlRewriteModule" type="UrlRewritingNet.Web.UrlRewriteModule, UrlRewritingNet.UrlRewriter"/>
    ...
    </modules>
</system.webServer>

Forms

There are .

Courier

Umbraco Courier 3.1.0 has been released to be compatible with Umbraco 7.6. If you are using Courier, you will need to update it to version 3.1.0.

Follow the to complete the upgrade

7.3.0 to 7.4.0

For manual upgrades:

Copy the new folder ~/App_Plugins/ModelsBuilder into the site
Do not forget to merge ~/Config/trees.config and ~/Config/Dashboard.config - they contain new and updated entries that are required to be there
- If you forget trees.config you will either not be able to browse the Developer section or you will be logged out immediately when trying to go to the developer section
You may experience an error saying Invalid object name 'umbracoUser' - this can be fixed by

Follow the to complete the upgrade.

7.2.0 to 7.3.0

NuGet will do the following for you. If you're upgrading manually make sure to also:

Delete bin/Microsoft.Web.Helpers.dll
Delete bin/Microsoft.Web.Mvc.FixedDisplayModes.dll
Delete bin/System.Net.Http.dll
Delete bin/System.Net.Http.*.dll (all dll files starting with System.Net.Http) except for System.Net.Http.Formatting.dll
Delete bin/umbraco.XmlSerializers.dll
Add this in the appSetting section of your web.config file: <add key="owin:appStartup" value="UmbracoDefaultOwinStartup" />

Other considerations:

WebApi has been updated, normally you don’t have to do anything unless you have custom webapi configuration:
- See this article if you are using WebApiConfig.Register:
- You need to update your web.config file to have the correct WebApi version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
MVC has been updated to MVC5
- You need to update your web.config file to have the correct MVC version references - this should be done by doing a compare/merge of your ~/web.config file with the ~/web.config file in the release
- The upgrader will take care of updating all other web.config’s (in all other folders, for example, the Views and App_Plugins folders) to have the correct settings
- For general ASP.NET MVC 5 upgrade details see:
It is not required that you merge the changes for the Examine index paths in the ExamineIndex.config file. However, if you do, your indexes will be rebuilt on startup because Examine will detect that they don’t exist at the new location.
It's highly recommended to clear the browser cache - the ClientDependency version is automatically bumped during installation which should force the browser cache to refresh, however in some edge cases this might not be enough.

Follow the to complete the upgrade.

7.1.0 to 7.2.0

Copy in the /Views/Partials/Grid (contains Grid rendering views).

Follow the to complete the upgrade.

7.0.2 to 7.1.0

Remove the /Install folder.

Follow the to complete the upgrade.

7.0.1 to 7.0.2

There was an update to the /umbraco/config/create/ui.xml which needs to be manually updated. The original element had this text:

<nodeType alias="users">
    <header>User</header>
    <usercontrol>/create/simple.ascx</usercontrol>
    <tasks>
    <create assembly="umbraco" type="userTasks" />
    <delete assembly="umbraco" type="userTasks" />
    </tasks>
</nodeType>

The usercontrol value has changed to: /create/user.ascx. This is a required change otherwise creating a new user will not work.
There is a breaking change to be aware of, full details can be found .

Follow the to complete the upgrade.

7.0.0 to 7.0.1

Remove all uGoLive dlls from /bin
- These are not compatible with V7
Move appSettings/connectionStrings back to web.config
- If you are on 7.0.0 you should migrate these settings into the web.config instead of having them in separate files in /config/
- The keys in config/AppSettings.config need to be moved back to the web.config <appSettings> section and similarly, the config/ConnectionStrings.config holds the Umbraco database connections in v7.0.0 and they should be moved back to the web.config <connectionStrings> section.
- /config/AppSettings.config and /config/ConnectionString.config can be removed after the contents have been moved back to web.config.
Delete all files in ~/App_Data/TEMP/Razor/
- Related to issues with razor macros

Follow the to complete the upgrade.

6.latest to 7

Read and follow

4.latest to 6

If your site was ever a version between 4.10.0 and 4.11.4 and you have upgraded to 6.0.0 install the and run it after the upgrade process is finished.
The DocType Mixins package is not compatible with v6+ and will cause problems in your Document Types.

Version 4

Version 4.10.x to 4.11.x

If your site was ever a version between 4.10.0 and 4.11.4 install the and run it after the upgrade process is finished.

Version 4.8.0 to 4.10.0

Delete the bin/umbraco.linq.core.dll file
Copy the new files and folders from the zip file into your site's folder
- /App_Plugins
- /Views
- Global.asax
Remove the Config/formHandlers.config file

Version 4.7.2 to 4.8.0

Delete the bin/App_Browsers.dll file
Delete the bin/App_global.asax.dll file
Delete the bin/Fizzler.Systems.HtmlAgilityPack.dll file
For people using uComponents 3.1.2 or below, 4.8.0 breaks support for it. Either upgrade to a newer version beforehand or follow the workaround

Version 4.7.1.1 to 4.7.2

Delete the bin/umbraco.MacroEngines.Legacy.dll file

Version 4.6.1 to 4.7.1.1

Delete bin/Iron*.dll (all dll files starting with "Iron")
Delete bin/RazorEngine*.dll (all dll files starting with "RazorEngine")
Delete bin/umbraco.MacroEngines.Legacy.dll
Delete bin/Microsoft.Scripting.Debugging.dll
Delete bin/Microsoft.Dynamic.dll

Upgrade your project

Before you upgrade

Legacy Umbraco

Upgrade to a new Major

Choose the correct .NET version

Upgrade your project using Visual Studio

Upgrade to a new Minor

Run an unattended upgrade

Enable the unattended upgrade feature

Run the upgrade

Boot order

Unattended upgrades in a load balanced setup

Version Specific Upgrades

Breaking changes

Release notes

Find your upgrade path

Upgrade from Umbraco 8 to the latest version

Prerequisites

Video Tutorial

Step 1: Content Migration

Step 2: File Migration

Step 3: Custom Code in the latest version

Examples of changes

Related Information

Migrate content to Umbraco 8

What are the limitations?

Versions supported

Database types supported

Known issues

Third party property editors

What will happen

How it works

Step 1: Upgrading to 7.14+

Step 2: Migrating content to Umbraco 8

Step 3: Files migration

Step 4: Post-migration checks

Minor upgrades for Umbraco 8

Note

Contents

Upgrade using NuGet

Upgrade manually from a zip file

Merge configuration files

Merge UI.xml and language files

Finalize

Run an unattended upgrade

Enable the feature

Check the ConfigurationStatus

Run the upgrade

Boot order

Unattended upgrades in a load balanced setup

Post installation

Potential issues and gotchas

Browser cache

Upgrade to Umbraco 7

Backup

.Net 4.5

HTML 5 browser support

Breaking changes

Examine

Xml Cache rebuild

Configuration changes

Medium Trust

Events

Tree events

Legacy business logic events

Property Editors

The Related Links property editor and XSLT

GUID -> Alias mapping

Parameter Editors

Database changes

Tags

Packages

For package developers

TypeFinder

JavaScript in menu actions

Use the recommended Umbraco uicontrols

Minor upgrades for Umbraco 7

Note

Contents

Upgrade using NuGet

Check the `ConfigurationStatus`

Check the `ConfigurationStatus`