Upgrading Umbraco 9 Cloud project to Umbraco 10
This article will provide steps on how to upgrade your Umbraco 9 project to Umbraco 10.
Are you using any custom packages or code on your Umbraco Cloud project?
You will need to ensure the packages you are using are available in Umbraco 10 and that your custom code is valid with the .NET 6 Framework.
Content
An overview of what you will find throughout this guide.
- Preprequisites
- 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
Go to the project in the Umbraco Cloud portal.
Navigate to Settings -> Advanced.
Scroll down to the Runtime Settings section.
Enable .NET 6 for each environment on your Cloud project.
Step 2: Clone down your environment
- Clone down the Development environment.
- Build and run the project locally.
- Log in to the backoffice.
- Restore content from your Cloud enviroment.
Step 3: Upgrade the project locally using Visual Studio
Open your project in Visual Studio - use the
csproj
file in the/src/UmbracoProject
folder.Right-click your project solution in the Solution Explorer.
Select Properties.
Select .Net 6.0 from the Target Framework drop-down in the General section of the Application tab.
Go to Tools > NuGet Package Manager > Manage NuGet Packages for Solution....
Navigate to the Browse tab.
Install the latest stable version of the "Microsoft.Extensions.DependencyInjection.Abstractions".
Navigate to the Installed tab.
Choose Umbraco.Cms.
Select your project.
Choose 10.0.0 from the Version drop-down.
Click Install to upgrade your project to version 10.
Follow the steps 9-12 to update the following packages as well:
Product | Version |
---|---|
Umbraco Deploy Cloud | 10.0.0 |
Umbraco Deploy Contrib | 10.0.0 |
Umbraco Forms | 10.0.0 |
Umbraco Deploy Forms | 10.0.0 |
Umbraco Cloud Identity | 10.0.2 |
Umbraco Cloud StorageProviders AzureBlob | 10.0.0 |
If you have more projects in your solution or other packages, make sure that these are also updated to support .NET 6 framework.
With the packages and projects updated, it is time to make some changes to some of the default files.
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",
Follow step 2 for the following files as well:
- appsettings.Development.json
- appsettings.Production.json
- appsettings.Staging.json
The final thing you need to do before testing the upgrade locally, is to remove a series of files no longer needed in your project.
Remove the following files and folders manually from your local project:
/wwwroot/umbraco
/umbraco/PartialViewMacros
/umbraco/UmbracoBackOffice
/umbraco/UmbracoInstall
/umbraco/UmbracoWebsite
/umbraco/config/lang
/App_Plugins/UmbracoForms
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.
- Remove the folders mentioned above on the Development environment using KUDU from the
repository
andwwwroot
folders. - Push the changes to the Development environment. See the Deploying from local to your environments article.
- Test everything on 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 on to 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
/App_Plugins/UmbracoForms
They need to be removed through KUDU from both the repository
and wwwroot
folders.