Major Upgrades

Before you start the upgrade

Before upgrading your Umbraco Cloud project to the latest major version, you must consider the version your project is already on. This will impact the upgrade flow you will be following.

Upgrading from a Short Term Supported (STS) version

When upgrading from an STS version, you must start by upgrading to the closest Long-term Support (LTS) major. If the version you are upgrading to is an STS version, you can upgrade to that version, directly from the closest LTS. You can upgrade directly if there are no LTS versions between the current one and the one you are upgrading to.

Refer to the Long-term support and EOL article to learn which versions are STS.

Example: Upgrading from Umbraco 11 (STS) to Umbraco 15 (STS)

Start by upgrading to the closest LTS. In this case, that is Umbraco 13. After that, you can upgrade directly from Umbraco 13 to Umbraco 15.

Upgrading from a Long Term Supported (LTS) version

When upgrading from an LTS version, you must start by looking at the versions between yours and the one you are upgrading to. Is there another LTS version in that line, you need to upgrade to that version first.

Refer to the Long-term support and EOL article to learn which versions are LTS.

Example: Upgrading from Umbraco 10 (LTS) to Umbraco 15 (STS)

Between version 10 and 15, there is another LTS version: Umbraco 13. The first step is therefore to upgrade to Umbraco 13. After that, you can upgrade directly from Umbraco 13 to Umbraco 15.

Version-specific upgrade notes

Look for the "Upgrade from/to Umbraco xx" boxes. These boxes contain important information about any extra steps needed for a specific version.

Prerequisites

• Follow the requirements for local development.

• An 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 back up the local database.

Step 1: Enable .NET

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

2. Navigate to Configuration -> 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.

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. Change the Target framework in the General section of the Application tab.

   1. Choose the version you set on your Cloud environment in Step 1.

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

2. Navigate to the Updates tab.

3. Select the version you are updated to, and follow the instructions:

Step 4: Finishing the Upgrade

1. Ensure the Unattended Upgrades feature is enabled.

2. Run the project locally.

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

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

1. Ensure that the project runs locally without any errors.

@addTagHelper *, Smidge
@inject Smidge.SmidgeHelper SmidgeHelper 

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>();
                });
    }

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

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

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

2. Test that everything works with the upgrade on the Cloud environment.

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

Step 5: Deploy the upgrade

The next part is to deploy the upgrade through to the production environment.

For major upgrades that include content migrations, the process can be extensive. This is especially true for sites with a large amount of content. In these cases, it is recommended to:

• Initiate a content freeze to prevent changes during the migration.

• Rearrange your custom hostname(s) to minimize website downtime.

You can choose between two approaches based on your needs:

• "With content freeze" - involves a more detailed upgrade process but helps reduce downtime on your live website.

• "Without content freeze" - provides a more straightforward process that may result in longer downtime on your live website.