Major Upgrades

Follow this guide when upgrading your Cloud project to a new major version of Umbraco CMS.

Are you using any custom packages or code on your Umbraco Cloud project?

You need to ensure that any packages you use are available in the latest version of Umbraco. You must also ensure your custom code is valid with the new .NET Framework version.

Breaking Changes

Ensure you know the Breaking changes in the latest version of Umbraco CMS.

Upgrading from Umbraco 9

When upgrading from Umbraco 9, you need to upgrade to the closest Long-term Support (LTS) major. For Umbraco 9 that is Umbraco 10. From Umbraco 10 you can then upgrade directly to the next long-term support which is Umbraco 13.

When upgrading from Umbraco 9 to Umbraco 10, follow the dropdowns named: "Upgrading from Umbraco 9" in the steps of the guide.

These are extra steps needed when going from Umbraco 9 to Umbraco 10.

Upgrading from Umbraco 10

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.

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

Prerequisites

• Follow the requirements for local development.

• A Umbraco Cloud project running the latest version of your current Umbraco CMS installation

• The latest .NET version is installed locally.

• At least 2 environments on your Cloud project.

• A backup of your project database.

  • Directly from your environment. See the Database backups article,

  • Or clone down, restore the project, and backup the local database.

Video Tutorials

Umbraco 10+

Upgrade tutorial Umbraco 10+

Umbraco 9 to 10 specific video tutorial

Upgrade tutorial Umbraco 9 to 10 on Cloud

Step 1: Enable .NET

1. Go to the project in the Umbraco Cloud portal.

2. Navigate to Settings -> Advanced.

3. Scroll down to the Runtime Settings section.

4. Ensure that the latest version of .NET is enabled for each environment on your Cloud project, by selecting it from the dropdown.

Runtime settings

Step 2: Clone down your environment

1. Clone down the Development environment.

2. Build and run the project locally.

3. Log in to the backoffice.

4. Restore content from your Cloud environment.

Step 3: Upgrade the project locally using Visual Studio

1. Open your project in Visual Studio - use the csproj file in the /src/UmbracoProject folder.

2. Right-click your project solution in Solution Explorer.

3. Select Properties.

1. Select the same .Net Target Framework drop-down in the General section of the Application tab as on your Cloud project.

Target Framework

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

2. Navigate to the Updates tab.

3. Select all packages made by Umbraco:

• Umbraco.Deploy.Forms

From v13, Umbraco.Deploy.Forms package has been replaced with Umbraco.Forms.Deploy package.

When upgrading to v13, follow these steps:

• Remove the Umbraco.Deploy.Forms package before updating the below mentioned packages.

• Install the Umbraco.Forms.Deploy package after the below mentioned packages are updated.

• Umbraco.Cms

• Umbraco.Deploy.Cloud

• Umbraco.Deploy.Contrib

• Umbraco.Forms

• Umbraco.Cloud.Identity.Cms

• Umbraco.Cloud.StorageProviders.AzureBlob

• Umbraco.Cloud.Cms.PublicAccess

Select the Microsoft.Extensions.DependencyInjection.Abstractions package if it appears in the list.

1. Click Update.

All packages checked in the Visual Studio Package manager and ready for update

If you have more projects in your solution or other packages, make sure that these are also updated to support the latest .NET framework.

Upgrading from Umbraco 9 - Update program.cs, appSettings.json and remove files.

• Update the Program class in the Program.cs file to the following: using Umbraco.Cms.Web.Common.Hosting;

  
  public class Program
      {
          public static void Main(string[] args)
              => CreateHostBuilder(args)
                  .Build()
                  .Run();
  
          public static IHostBuilder CreateHostBuilder(string[] args) =>
              Host.CreateDefaultBuilder(args)
                  .ConfigureUmbracoDefaults()
                  .ConfigureWebHostDefaults(webBuilder =>
                  {
                      webBuilder.UseStaticWebAssets();
                      webBuilder.UseStartup<Startup>();
                  });
      }

• Re-enable the appsettings IntelliSense by updating your schema reference in the appsettings.json file from:

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

To:

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

Apply this change to the following files as well:

• appsettings.Development.json

• appsettings.Production.json

• appsettings.Staging.json

Remove the following files and folders manually from your local project:

• /wwwroot/umbraco

• /umbraco/PartialViewMacros

• /umbraco/UmbracoBackOffice

• /umbraco/UmbracoInstall

• /umbraco/UmbracoWebsite

• /umbraco/config/lang

Step 4: Finishing the Upgrade

1. Enable the Unattended Upgrades feature.

2. Run the project locally.

3. Log in to the Umbraco backoffice to verify the upgrade has happened.

   • If you are unable to login locally via Umbraco ID and URL shows /umbraco/authorizeupgrade?redir= then this is because of the Unattended Upgrades setting. It needs to be set to true and deployed to the environment before performing the upgrade.

4. Disable the Unattended Upgrades feature if necessary.

5. Build and run the project to verify everything works as expected.

Target Framework

Upgrading to Umbraco 14

• Update _ViewImports.cshtml file

In Umbraco 14, Smidge has been removed from the CMS.

In the _ViewImports.cshtml of your project, remove the following lines:

@addTagHelper *, Smidge
@inject Smidge.SmidgeHelper SmidgeHelper 

Otherwise, it will cause an error on the frontend.

• Update program.cs file

Remove u.UseInstallerEndpoints(); from the program.cs file to avoid issues when running the project.

Once the Umbraco project runs locally without any errors, the next step is to deploy and test on the Cloud Development environment.

Upgrading from Umbraco 9 - Remove files from the development environment.

• /wwwroot/umbraco

• /umbraco/PartialViewMacros

• /umbraco/UmbracoBackOffice

• /umbraco/UmbracoInstall

• /umbraco/UmbracoWebsite

• /umbraco/config/lang

The files and folder above need to be removed on the Development environment through KUDU -> Debug Console -> CMD -> Site -> from both the repository and wwwroot folders.

1. Push the changes to the Development environment. See the Deploying from local to your environments article.

2. Test everything in the Development environment.

We highly recommend that you go through everything in your Development environment. This can help you identify any potential errors after the upgrade, and ensure that you are not deploying any issues onto your Live environment.

Step 5: Going live

Upgrading from Umbraco 9 - Remove files from staging/live the environment.

Before deploying the upgrade to your next environment, you will need to remove the folders you also removed from Kudu on your Development environment.

The files are:

• /wwwroot/umbraco

• /umbraco/PartialViewMacros

• /umbraco/UmbracoBackOffice

• /umbraco/UmbracoInstall

• /umbraco/UmbracoWebsite

• /umbraco/config/lang

They need to be removed through KUDU -> Debug Console -> CMD -> Site -> from both the repository and wwwroot folders.

Once everything works as expected in the development environment, you can push the upgrade to the live environment.

• Working locally with Umbraco Cloud

• KUDU on Umbraco Cloud