Quick guide: upgrading Umbraco 9 to 10
Tags: umbraco
Published: 2022-11-04 16:38:51

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](https://umbraco.com/products/knowledge-center/long-term-support-and-end-of-life/)

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](https://our.umbraco.com/documentation/Fundamentals/Setup/Server-Setup/runtime-modes?_ga=2.242434690.1001545183.1667578030-912889740.1667578030)
- Updated dependencies
- Improved performance

## How

Umbraco provide a really handy series of steps in their [docs](https://our.umbraco.com/documentation/Fundamentals/Setup/Upgrading/version-specific#version-9-to-version-10).

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](https://our.umbraco.com/Documentation/Implementation/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](https://github.com/leekelleher/umbraco-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](https://our.umbraco.com/documentation/Umbraco-Cloud/Upgrades/Upgrading-from-9-to-10/)
[Umbraco Forms upgrade notes](https://our.umbraco.com/documentation/Add-ons/UmbracoForms/Installation/Version-Specific#version-10)
[Umbraco Deploy upgrade notes](https://our.umbraco.com/documentation/Add-ons/Umbraco-Deploy/Upgrades/version-specific#version-10)