A Step-by-Step Guide to Upgrading Your Website from Umbraco 8 to Umbraco 13 LTS

Umbraco 8 reached its end of life (EOL) on 24th February 2025. If your website is still running on this version, it’s now officially unsupported—no further bug fixes, security patches, or new features will come from Umbraco HQ. That’s a precarious position in today’s fast-moving digital world. Upgrading to Umbraco 13, the latest Long-Term Support (LTS) version, isn’t just about keeping up; it’s about unlocking superior performance, modern capabilities, and a future-proof foundation built on .NET 8.

However, there’s no direct jump from Umbraco 8 to Umbraco 13. The journey involves multiple steps, a major framework transition, and some code refactoring. Fear not—I’m here to guide you through it all. In this blog post, we’ll explore the upgrade path, the shift from .NET Framework to .NET Core, key API and architectural changes, and some clever tools and strategies (like uSync and GitKraken Worktrees) to streamline the process. Whether you’re a seasoned developer or overseeing a team tackling this upgrade, this guide is for you.

Why Upgrade? The Risks of Lingering on Umbraco 8

Before we dive into the how-to, let’s consider why this matters. Umbraco 8, built on the .NET Framework, was brilliant in its time, but it’s now outdated. Microsoft has pivoted to .NET Core (now simply .NET), and Umbraco followed suit with version 9 in 2021. Staying on Umbraco 8 means:

Security Vulnerabilities: No more patches for emerging threats.

Performance Lag: You’re missing out on .NET Core’s speed and scalability improvements.

Feature Stagnation: Umbraco 13 offers modern tools like Block Grid Editor, Webhooks, and headless APIs—none of which are available in version 8.

Umbraco 13, originally released in December 2023, is an LTS version supported until Q4 2026. It continues to receive feature updates, with the latest being version 13.7.0, released on 27th February 2025. Running on .NET 8, it aligns with Microsoft’s LTS schedule and delivers a stable, feature-rich platform. Upgrading isn’t optional—it’s critical. Let’s chart the course.

The Upgrade Path: Umbraco 8 to Umbraco 13 via Umbraco 10

You can’t leap straight from Umbraco 8 to Umbraco 13. The shift from .NET Framework to .NET Core means there’s no direct database migration or codebase compatibility. Instead, Umbraco advises an incremental approach, with Umbraco 10—the previous LTS version—as the key stepping stone.

Here’s the plan at a glance:

Umbraco 8 to Umbraco 10: This step manages the initial framework shift and database migration compatibility.

Umbraco 10 to Umbraco 13: A smoother upgrade between .NET Core versions, refining your codebase and embracing new features.

Why Umbraco 10 first? It’s the bridge that supports migrations from Umbraco 8’s database schema and runs on .NET 6 LTS (the predecessor to .NET 8). Once you’re on Umbraco 10, moving to 13 is a simpler NuGet package update. Let’s break it down.

Upgrading Your Website From Umbraco 8 To Umbraco 13 LTS A Comprehensive Guide Theplan

Step 1: Umbraco 8 to Umbraco 10 – Crossing the Framework Divide

Umbraco 8 runs on .NET Framework 4.7.2 or higher, while Umbraco 10 operates on .NET Core 6 (specifically 6.0.5 or later). This isn’t just a version bump—it’s a fundamental change. .NET Core is cross-platform, modular, and faster, but it requires reworking custom code and adapting to Umbraco’s new structure.

Process Overview

Start a New Umbraco 10 Site: Don’t attempt to “upgrade” your existing Umbraco 8 project in situ. Set up a fresh Umbraco 10 instance using NuGet or the CLI.
Migrate Content: Connect your new Umbraco 10 site to your Umbraco 8 database. Umbraco 10 includes migrations to update the schema. Log in to the back office to ensure your content (documents, media, etc.) is intact.
Reimplement Code and Templates: Custom code, Razor views, and third-party packages won’t transfer automatically. You’ll need to port them manually to .NET Core conventions.
Test Thoroughly: Check everything—front-end rendering, backoffice functionality, and integrations.

Key Changes to Understand

Framework Shift: Farewell to System.Web; hello to ASP.NET Core. This impacts routing, middleware, and dependency management.
API and Namespace Changes: Umbraco’s APIs have evolved. For instance, Umbraco.Web.PublishedModels becomes Umbraco.Cms.Web.Common.PublishedModels. Refer to Umbraco’s API documentation for details.
Dependency Injection (DI): Umbraco 8 had rudimentary DI, but .NET Core relies on it heavily. Inject services like IContentService or IMediaService into controllers via constructors rather than accessing them statically (e.g., Services.ContentService).
Surface Controllers in Partial Views: Surface Controllers, used in Umbraco 8 for custom backend logic in partial views, have shifted in purpose. In Umbraco 13, they still exist (mainly for form posts), but for rendering partials, View Components are now preferred.

From Surface Controllers to View Components

Here’s an example of how this transition looks. In Umbraco 8, you might have a Surface Controller rendering a partial view like this:

Text Box

In Umbraco 10 (and beyond), this becomes a View Component:

Text Box

Notice the similarities: the core logic—checking SelectedPages and falling back to _myService.GetLatest(), plus assigning SomeText remains unchanged. The shift is structural: dependency injection is explicit, and the rendering moves from PartialView to View with a full path. Invoke it in your Razor view with:

@await Component.InvokeAsync("RenderExample", new { content = Model.Content })

Tools to Ease the Pain: uSync Migrations

Content migration can be complex, especially with legacy editors like Nested Content or Grid Layout. Enter uSync Migrations, a brilliant tool for converting these to Umbraco 10+ equivalents: Block List and Block Grid.

Nested Content to Block List: uSync Migrate transforms Nested Content data into Block List structures, preserving your content while upgrading the editor.
Grid to Block Grid: It maps Grid layouts to Block Grid, Umbraco’s modern, flexible grid editor.

Install uSync on both your Umbraco 8 and 10 sites. Export content and settings from 8, run uSync Migrate to convert legacy formats, then import into 10. It’s not infallible for every scenario, but it drastically reduces manual effort.

If you have legacy property editors which are not compatible with Umbraco 10+, then uSync Migrations has you covered for some of which you may be using. Check out https://github.com/Jumoo/uSyncMigrations/tree/main/uSync.Migrations.Migrators/Community for a list of community packages which have converters right from the get go.

Not seeing a converter for some of your packages? Create your own converter! This project may help you get started: https://github.com/Jumoo/uSyncMigrations/tree/main/MyMigrations.

#H5YR Kevin Jump for making this!

Step 2: Umbraco 10 to Umbraco 13 – Upgrading .NET Core Versions

With Umbraco 10 running on .NET 6 LTS, you’re already in the .NET Core ecosystem. Upgrading to Umbraco 13 moves you to .NET 8 LTS, bringing performance enhancements, C# 12 features, and Umbraco updates like Webhooks and refined Block Grid editing.

Process Overview

Update Target Framework: In your .csproj, change <TargetFramework>net6.0</TargetFramework> to <TargetFramework>net8.0</TargetFramework>.

Upgrade NuGet Packages: Update Umbraco.Cms to the latest 13.x version (e.g., 13.7.0). Verify compatibility for third-party dependencies.

Adjust Code: Most changes are minor, but review breaking changes in Umbraco 13 (e.g., migration transaction updates) and .NET 8 (e.g., nullable reference tweaks).

Test Again: Ensure everything functions on the new runtime.

Notable Differences

.NET 6 to .NET 8: .NET 8 improves memory management and startup times. Most Umbraco 10 code should work as-is, but test for runtime nuances.

API Refinements: Umbraco 13 tweaks APIs further. For example, PagedModel shifts from Umbraco.New.Cms.Core.Models to Umbraco.Cms.Core.Models.

DI Continuity: Dependency injection patterns remain consistent, so your Umbraco 10 DI setup should transition smoothly.

Practical Tips for a Smooth Upgrade

Backup Everything: Before you start, back up your Umbraco 8 database and codebase. Things will go wrong—be prepared to revert.

Audit Packages: Confirm whether your Umbraco 8 packages (e.g., Forms, uSync) have .NET Core versions. Replace or rewrite unsupported ones.

Leverage Documentation: Umbraco’s official upgrade guides (e.g., “Upgrade from Umbraco 8 to the latest version”) and API docs are invaluable.

Test Incrementally: Validate after each step—Umbraco 8 to 10, then 10 to 13. Catch issues early.

Engage the Community: The Umbraco forums and Discord are packed with people who’ve navigated this. Seek help if you’re stuck.

Upgrading Your Website From Umbraco 8 To Umbraco 13 LTS A Comprehensive Guide Smoothupgrade

The Payoff: Why Umbraco 13 is Worth It

After all this effort, what’s the reward? Umbraco 13 isn’t just a maintenance update—it’s a significant advancement:

Performance: .NET 8’s optimisations make your site faster and more scalable.

Modern Editing: Block Grid and Rich Text Editor enhancements empower content editors.

Headless Ready: Built-in Content Delivery and Media APIs enable decoupled architectures.

Longevity: LTS support until 2026 ensures stability without frequent upgrades.

Why Not Umbraco 15? The LTS vs. STS Debate

Umbraco 15 is the latest Standard-Term Support (STS) release (at the time of writing), bringing cutting-edge features and running on the freshest .NET version (likely .NET 9, given Microsoft’s annual cadence). So why are we focusing on upgrading to Umbraco 13 LTS instead of jumping to 15? It’s all about stability, longevity, and practicality—key considerations for any production website.

Umbraco operates on a dual-release strategy: Long-Term Support (LTS) versions, like 13, and Standard-Term Support (STS) versions, like 15. LTS releases are supported for three years—until Q4 2026 for Umbraco 13—offering a stable, battle-tested platform with regular bug fixes and security patches. STS releases, on the other hand, are supported for just 18 months and serve as a testing ground for new features and innovations. They’re ideal for early adopters or projects that can afford frequent upgrades, but they come with a shorter lifecycle and less certainty.

Here’s why sticking with Umbraco 13 LTS makes sense for this upgrade:

Extended Support: With support until 2026, Umbraco 13 gives you breathing room—no need to plan another major upgrade soon after this one. Umbraco 15’s STS window, ending around mid-2026, would demand quicker action.

Proven Stability: Umbraco 13, originally released in December 2023 and now at version 13.7.0, has had time to mature. It’s been widely adopted, with kinks ironed out through updates. Umbraco 15, being newer, carries a higher risk of unforeseen issues.

Resource Efficiency: Upgrading from Umbraco 8 to 13 is already a significant undertaking—jumping to 15 would add complexity, as it might involve adapting to even newer .NET features or CMS changes beyond what 13 requires.

Package Support: Umbraco 14 introduced significant changes to how packages are built, shifting to a new extension model that not all package developers have fully adopted yet. While Umbraco 13 benefits from broad compatibility with established packages, moving to 14+ (and thus 15) could mean gaps in support. That said, many popular packages—like uSync, Contentment, The Dashboard, and my own Client Drawer—are readily available for 15, reflecting strong community effort. Still, less widely-used or older packages might not have made the leap, potentially requiring custom workarounds or replacements on 15 that aren’t needed on 13.

Business Continuity: For live websites, LTS versions minimise disruption. You get modern capabilities (like Block Grid and headless APIs) without the bleeding-edge risks of an STS release.

That’s not to say Umbraco 15 isn’t exciting—it’s a glimpse into the CMS’s future, and some teams might opt for it to leverage the latest tools. But for most organisations, especially those moving from an EOL version like Umbraco 8, Umbraco 13 LTS strikes the perfect balance of modernity and dependability. Once you’re settled on 13, you can always evaluate 15 (or beyond) when the next LTS arrives.

Managing the Codebases: GitKraken Worktrees to the Rescue

Upgrading across three versions—Umbraco 8, 10, and 13—means handling multiple codebases. You might need to maintain your live Umbraco 8 site while developing Umbraco 10, then progress to 13. Typically, this involves branch switching, premature commits, or separate repositories—none of which are ideal.

Cue GitKraken’s Worktree feature, a fantastic solution for this scenario. Worktree allow you to isolate each version as independent working directories on your filesystem, all linked to the same repository. Here’s why it’s a winner:

No Branch Switching: Keep Umbraco 8 (production), 10 (migration), and 13 (final) as separate folders. Work on all three simultaneously without stashing or committing too soon.

Independent Development: Test changes in Umbraco 10 while referencing your Umbraco 8 baseline, then port to 13—all without losing context.

Streamlined Workflow: GitKraken’s visual interface tracks changes across these directories, making it easy to commit, merge, or roll back as needed.

Set it up by creating a Worktree in GitKraken, adding your repository, and defining paths for each version (e.g., /versions/v8, /versions/v10, /versions/v13). It’s like having three sandboxes without the Git acrobatics.

Not using GitKraken? I’m not aware of any other Git GUI’s which have this feature, however if you’re a maverick and experienced in git command line it is also available (https://git-scm.com/docs/git-worktree).

Upgrading Your Website From Umbraco 8 To Umbraco 13 LTS A Comprehensive Guide Gitkracken

For the Developers…

We all know an upgrade of this scale isn’t straightforward—especially when you’re not only updating every layer of the CMS but also switching the underlying framework. Our developers have ventured into uncharted territories of code and scenarios that aren’t always covered in the documentation. Here’s some valuable advice they’d like to share from their experience:

Nested Content Transition: Nested Content is now considered a legacy property editor, and the recommendation is to adopt Block List as the standard. Block Lists can be configured to deliver a nearly identical editor experience to Nested Content—and often more—making them a powerful replacement. While uSync Migrations can handle converting your data types and content to this new model, be prepared for some code breakage. In Umbraco 8, Nested Content values were represented as an enumerable object—a simple collection of nested items. In contrast, Block Lists in Umbraco 10+ are still enumerable, though each item is now a BlockListItem object containing separate Content and Settings models. The Content object corresponds to your original nested content item. This shift requires a small but essential update to your LINQ code when iterating over these collections. Here’s how:

Nested Content:

Text Box

Block List:

Text Box

Umbraco Forms :–

Upgrading Umbraco CMS from version 10 to the latest version is relatively straightforward, but the same can’t always be said for Umbraco Forms. In our experience, attempting to leap too far in Forms versions alongside the CMS upgrade can lead to trouble. Each minor version of Forms may introduce new database migrations to update the schema, and jumping from, say, Forms 10.5.7 to 13.4.0 (the latest versions at the time of writing) proved too significant a leap. The accumulated schema changes caused migrations to fail, preventing the site from starting. Our solution? Upgrade Forms to an interim version like 13.2.2 first, run the site to let the migrations settle, then proceed to the latest version (e.g., 13.4.0).

If you encounter errors about missing columns on first boot, don’t panic. Navigate to the Umbraco back office, head to the Packages section, select the ‘Installed’ tab, locate Umbraco Forms, and click ‘Run pending migrations’. This should resolve any lingering database issues.

Closing Thoughts

Upgrading from Umbraco 8 to Umbraco 13 is a marathon, not a sprint. It’s an opportunity to modernise your site, shed legacy constraints, and adopt a CMS ready for the future. By stepping through Umbraco 10, adapting to .NET Core 6 and then 8, rethinking APIs and controllers, and using tools like uSync Migrations and GitKraken Worktrees, you can make it manageable—and even enjoyable.

Do you have an Umbraco 8 website that needs upgrading but don’t know where to begin? If you need a team of experienced, certified Umbraco developers to help you and your site on this path, look no further. Contact us today, and our friendly team will be happy to speak with you.