Major Upgrades
Follow this guide when upgrading your Cloud project to a new major version of Umbraco CMS. For example when upgrading from 10 to 11.
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 also need to ensure that your custom code is valid with the new .NET Framework version.
Breaking Changes
Upgrading from Umbraco 9
If upgrading from Umbraco 9 to a later major version, 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 the latest major.
- A Umbraco Cloud project running the latest version of Umbraco
- At least 2 environments on your Cloud project.
- A backup of your project database.
- Or clone down, restore the project, and backup the local database.
Video Tutorial
- Go to the project in the Umbraco Cloud portal.
- Navigate to Settings -> Advanced.
- Scroll down to the Runtime Settings section.
- Ensure that the latest version of .NET is enabled for each environment on your Cloud project.

Runtime settings
- Clone down the Development environment.
- Log in to the backoffice.
- Restore content from your Cloud environment.
- Open your project in Visual Studio - use the
csproj
file in the/src/UmbracoProject
folder. - Right-click your project solution in Solution Explorer.
- Select Properties.

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

Target Framework
- Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution....
- Navigate to the Updates tab.
- Checkmark all packages made by Umbraco:
- Umbraco.Cms
- Umbraco.Deploy.Cloud
- Umbraco.Deploy.Contrib
- Umbraco.Forms
- Umbraco.Deploy.Forms
- Umbraco.Cloud.Identity.Cms
- Checkmark the
Microsoft.Extensions.DependencyInjection.Abstractions
package if it appears in the list. - Select 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.
- Update the
Program
class in theProgram.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
- Run the project locally.
- Log in to the Umbraco backoffice to verify the upgrade has happened.
- Disable the Unattended Upgrades feature.
- Build and run the project to verify everything works as expected.

Target Framework
Once the Umbraco project runs locally without any errors, the next step is to deploy and test on the Cloud 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.

- Push the changes to the Development environment. See the Deploying from local to your environments article.
- 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.
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.
Last modified 17d ago