From Umbraco 13 to 17: My Upgrade Journey and Lessons Learned

Published by Debasish Gracias on 5 February 2026

Upgrading Umbraco isn’t just about bumping a version number—it’s about embracing change in the ecosystem, the framework, and the way we build. Recently, I took the plunge of upgrading my personal blogging site from Umbraco 13 (LTS) to Umbraco 17 (LTS), and I want to share my experience and the lessons learned.

Why This Upgrade Felt Different

This wasn’t a routine patch update. Moving from 13 to 17 meant stepping into a new .NET framework (from net8.0 to net10.0) and adopting the modern back office architecture(Bellissima) that Umbraco introduced in v14 and refined in v17. The good news? It’s a direct LTS-to-LTS upgrade path, and Umbraco handles database migrations automatically. The challenge? Making sure everything else in the stack plays nicely.

My Prerequisites Checklist

Before diving in, I made sure I had the right setup:

Visual Studio 2026 (or a compatible version).
.NET 10 SDK installed.
Backups of database and project files (trust me, don’t skip this).
Upgraded my Umbraco 13 project to the latest patch version first, and updated all packages to their latest v13-compatible versions.

This prep work saved me from a lot of headaches later.

Step 1: Updating the Target Framework

The first step was straightforward but critical:

Edited the .csproj file to target net10.0.
Double-checked that all custom libraries and referenced projects were compatible.

Step 2: NuGet Package Updates

Next, I updated the Umbraco Cms packages to 17.1.0 and ensure all custom and third party packages are either compatible with v17 or temporarily removed.

Step 3: Startup/Middleware Adjustments

Umbraco 17’s streamlined hosting model meant cleaning up my Program.cs.

Removed the deprecated line:
```
u.UseInstallerEndpoints();
```
Aligned the startup code with the new minimal hosting approach.

This was one of those “small change, big impact” moments.

Step 4: Handling Breaking Changes

Models Builder: I had to delete the old generated models folder, run the project (yes, it errored), and then regenerate models via the back office.
Rich Text Editor: Umbraco 17 now uses TipTap instead of TinyMCE. Migration was automatic, but I still reviewed datatypes and custom extensions.

Step 5: Running the Upgrade

Starting the application triggered Umbraco’s maintenance mode. From there, I had two options:

Complete the upgrade via the back office interface.
Configure an unattended upgrade in appsettings.json

I went with the back office route—it gave me more visibility into what was happening.

Step 6: Post-Upgrade Testing

Once the upgrade completed, I spent time in a staging environment testing everything:

Verified the back office loaded correctly.
Checked all content and functionality.
Tested custom features and third-party packages.

Final Thoughts

Upgrading from Umbraco 13 to 17 was more than just a technical exercise—it was a reminder of how fast the ecosystem evolves. The new back office feels modern, the framework upgrade opens doors for performance improvements, and the overall developer experience is smoother.

Would I recommend the upgrade? Absolutely—but only after careful preparation, backups, and thorough testing.