Upgrading Umbraco 9 Cloud project to Umbraco 10

This article will provide steps on how to upgrade your Umbraco 9 project to Umbraco 10.

Content

An overview of what you will find throughout this guide.

• Prerequisites
• Video Tutorial
• Step 1: Enable .NET 6
• Step 2: Clone down your project
• Step 3: Upgrade the project locally using Visual Studio
• Step 4: Deploy and Test on Umbraco Cloud
• Step 5: Going live

Prerequisites

• An Umbraco 9 Cloud project running the latest version of Umbraco 9

• 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 and restore the project, and take a backup of the local database.

Video Tutorial

Step 1: Enable .NET 6

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

2. Navigate to Settings -> Advanced.

3. Scroll down to the Runtime Settings section.

4. Enable .NET 6 for each environment on your Cloud project.

   

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

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 the Solution Explorer.

3. Select Properties.

   

4. Select .Net 6.0 from the Target Framework drop-down in the General section of the Application tab.

   

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

6. Navigate to the Browse tab.

7. Install the latest stable version of the "Microsoft.Extensions.DependencyInjection.Abstractions".

8. Navigate to the Installed tab.

9. Choose Umbraco.Cms.

10. Select your project.

11. Choose 10.0.0 from the Version drop-down.

12. Click Install to upgrade your project to version 10.

    

Follow the steps 9-12 to update the following packages as well:

With the packages and projects updated, it is time to make some changes to some of the default files.

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

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

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

   • /wwwroot/umbraco
   • /umbraco/PartialViewMacros
   • /umbraco/UmbracoBackOffice
   • /umbraco/UmbracoInstall
   • /umbraco/UmbracoWebsite
   • /umbraco/config/lang

4. Update the Umbraco Forms related files and folders according to the Upgrading - version specific for version 10 article.

5. Choose your Database configuration:

   • To re-use the existing LocalDB database, configure the ConnectionStrings or use the PreferLocalDbConnectionString setting.
   • To use the default SQLite database, skip this step.

6. Build and run your project locally to verify the Umbraco 10 upgrade.

   

Step 4: Deploy and Test on Umbraco Cloud

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

1. Remove the folders mentioned above on the Development environment using KUDU from the repository and wwwroot folders.
2. Push the changes to the Development environment. See the Deploying from local to your environments article.
3. Test everything in the Development environment.

We highly recommend that you go through everything on 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

Before deploying the upgrade to your Live environment, you will need to remove the folders you also removed from both your local instance and your Development environment.

The files are:

• /wwwroot/umbraco
• /umbraco/PartialViewMacros
• /umbraco/UmbracoBackOffice
• /umbraco/UmbracoInstall
• /umbraco/UmbracoWebsite
• /umbraco/config/lang

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

They need to be removed through KUDU from both the repository and wwwroot folders.