Quick guide: upgrading Umbraco 9 to 10

Hey folks, here's a quick guide on how to upgrade Umbraco 9 up to version 10, with some extras around Umbraco Cloud. There's a few gotchas in there, so wanted to share some notes all in one place.

Why

First of all, the biggest reason for upgrading is to align with the Long Term Supported (LTS) version of Umbraco. i.e. if there is a version of Umbraco to upgrade to, then this is the one that's going to get support for a longer period of time.

More details on that here: Umbraco LTS

Outside of that, there are a few new handy updates:

• Improved cross-platform support, now using SQLite for development
• WebP support for optimised images
• User permissions based on languages
• Read only mode for properties
• Runtime modes
• Updated dependencies
• Improved performance

How

Umbraco provide a really handy series of steps in their docs.

Check the link for full details, but here's a short summary:

• Take some backups!
• Update to .NET 6
• Update {ProjectName}.csproj to enable implicit usings and nullable reference types:

<PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
</PropertyGroup>

• Upgrade package references, the Umbraco HQ packages are now using 10.x.x. Check any other dependencies if you have them added, e.g. Contentment
• Update Program.cs with the following:

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

• Remove the following files/folders used by Umbraco:

/wwwroot/umbraco
/umbraco/PartialViewMacros
/umbraco/UmbracoBackOffice
/umbraco/UmbracoInstall
/umbraco/UmbracoWebsite
/umbraco/config/lang
/umbraco/config/appsettings-schema.json

• Remove the following files/folders used by Umbraco Forms:

/App_Plugins/UmbracoForms
/Views/MacroPartials/InsertUmbracoFormWithTheme.cshtml
/Views/MacroPartials/RenderUmbracoFormScripts.cshtml
/Views/Partials/Forms/

• To re-enable the appsettings IntelliSense, update your appsettings.json

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

• Commit your changes and get ready to deploy!

Note, if using Umbraco Cloud, you'll also need to delete the files/folders through KUDU from both the repository and wwwroot folders before pushing the upgrade changes.

References

Umbraco Cloud upgrade notes
Umbraco Forms upgrade notes
Umbraco Deploy upgrade notes