This is part two in a series of blogs about common things you'll encounter when updating Umbraco 13 to 16. In this part, we'll look into the prerequisites for an update, perform the first upgrade steps and fix a number of errors as a result of the upgrade steps.
Prerequisites
Let's look at what needs to be in place before you can start the update.
Umbraco 16 requires .NET 9, whereas Umbraco 13 used .NET 8. So you'll need to have .NET 9 installed on your development system. If you're using Visual Studio, you need at least version 17.12, which is the first version with .NET 9 support.
There are also two notable missing features in Umbraco 14+ that were still present in Umbraco 13 (although deprecated): Nested Content and Macros. You'll need to migrate these to Block Lists and Blocks, respectively. I prefer handling migrations while still on Umbraco 13, so everything is up-to-date before the upgrade and there's one less thing to worry about during the upgrade process. I might cover this in more detail in a future blog.
Lastly, before any update, always ensure you're on the latest Umbraco 13 version and using the latest compatible versions of all your packages. This gives you the best chance of a smooth upgrade.
Update .NET Version
The first upgrade step is updating the .NET version. Umbraco 13 uses .NET 8, while Umbraco 16 uses .NET 9. Simply update the Target Framework in all project files:
<!-- Original -->
<TargetFramework>net8.0</TargetFramework>
<!-- Updated -->
<TargetFramework>net9.0</TargetFramework>
Update NuGet Packages
Next, update all NuGet packages. Start with the Umbraco packages, then move on to the others.
Remove the Umbraco.Cms.Web.Backoffice package. This package no longer exists in Umbraco 16.
Update all Umbraco packages to the latest version (16.1.1 at the time of writing). Due to dependencies, updating via the NuGet Package Manager can be tricky. I usually update the version numbers directly in the project file(s) using find/replace.
Update all other NuGet packages. Be aware that some popular packages, like Contentment and SEOChecker, may not have final versions for Umbraco 16 yet. You might need to check for pre-release versions.
Once all packages are updated, you'll likely see a massive amount of build errors—this is expected. Let's fix some common ones.
Fix Caching and Especially the Models Builder
Umbraco 15 introduced the HybridCache as a replacement for NuCache. As a result, IPublishedSnapshotAccessor is no longer available. Any code using it needs to be updated.
Most errors will probably come from models generated by the Models Builder, as every generated model references IPublishedSnapshotAccessor.
Manually updating all models would be a waste of time. Fortunately, Søren Kottal wrote an excellent blog on how to fix this quickly:
Quick fix for IPublishedSnapshotAccessor issues
Outside of Models Builder, you can use IPublishedContentCache instead of IPublishedSnapshotAccessor. Updating the code should be straightforward.
Other Small Suggestions and Fixes
Larger topics—like updating UmbracoApiController, UmbracoAuthorizedApiController, and localization—will be covered in separate blogs. But here are a few small things you might run into:
You'll notice many more functions are now async. In most cases, it's just a matter of making the wrapping function async and using the await keyword.
If a function name has changed, it's usually obvious what the new name is. For example, Save functions are now often split into Create and Update.It's not perfect yet, but most code now uses GUIDs for identifiers (e.g., for nodes or users).
This is reflected in the fact that UmbracoCore.Constants.Security.SuperUserId is deprecated. You now need to use UmbracoCore.Constants.Security.SuperUserKey.
Since SuperUserKey is not a constant, you can't use it as a default parameter value in functions anymore.
That’s it for now! Hopefully this gives you a solid start on upgrading to Umbraco 16. I’ll be covering more topics like API controller changes, localization tweaks, and migrating deprecated features in future posts. If you’ve run into anything interesting or hit a snag during your own upgrade, I’d love to hear about it—drop a comment or reach out!
Top comments (1)
Another thing to note for Umbraco Cloud users, is that the packages Umbraco.Cloud.Cms.PublicAccess and Umbraco.Cloud.Identity.Cms has been consolidated into one Umbraco.Cloud.Cms package. So you need to uninstall the two previous ones, and install the new one!