The Definitive Guide to Migrating from Umbraco 7 to Umbraco 13

Migrating an Umbraco 7 website to Umbraco 13 is not a simple upgrade; it is a re-platforming project. Umbraco 7 runs on the legacy .NET Framework, while Umbraco 13 (a Long-Term Support version) runs on modern .NET (formerly .NET Core). This fundamental change in underlying technology means there is no direct "upgrade button."

This guide will walk you through the professional, robust approach to migration, which involves moving your content via a database upgrade path while simultaneously rebuilding your codebase.

1. Understanding the Strategy

Before writing a single line of code, you must understand the path ahead. You cannot jump directly from v7 to v13. Instead, you must take your database through a series of "hops" to migrate its schema, while your code must be almost entirely rewritten to support modern .NET architecture.

The image below visualizes this dual-track process:

Key Concepts:

• Database Migration Path: We will upgrade the database from v7 -> v8 -> v10 -> v13. The jump from v7 to v8 is the most critical as the database schema changes significantly to support "NuCache." Subsequent jumps are easier.

• Code Rebuild: Your MVC Controllers, Surface Controllers, Event Handlers, and Views written for .NET Framework will not work in .NET Core. They must be rewritten using modern dependency injection patterns.

Phase 1: Preparation and Cleanup (V7)

A successful migration starts with a clean house. Trying to migrate a messy v7 site will result in failure during the database upgrade steps.

Prerequisite: Backups! Before doing anything, take a full backup of your V7 database and media files.

Step-by-Step Cleanup:

1. Upgrade to the latest V7: Ensure your current site is running Umbraco 7.15.7 (or the absolute latest v7 patch). This version includes essential migration tools.

2. Remove Unused Data: Delete old content versions, empty the recycle bin, and delete unused media types and document types. The smaller your database, the faster the migration.

3. Uninstall Legacy Packages: Packages like "Archetype" or "Nested Content" may not have direct upgrade paths. You will need to plan to convert this data to modern equivalents like "Block List" or "Block Grid" later.

4. Run the Health Check: Umbraco 7.15 includes a "Migration" health check in the Developer section. This is your most critical tool.

As shown in the screenshot below, the Health Check will scan your data for obsolete property editors and data types that will break the migration to V8. You must fix every red 'X' before proceeding.

Phase 2: The Database "Hops" (V7 -> V8 -> V10 -> V13)

This phase focuses solely on getting your content and schema into a V13-compatible database format. We are not concerned with front-end rendering yet.

Step 2a: The Big Jump (V7 to V8)

1. Create a fresh, empty Umbraco v8.18 project.

2. Point its connection string to your cleaned-up V7 database.

3. Copy your /media folder from the V7 site to the V8 site.

4. Run the V8 site. The installer will detect the old database version and begin the migration.

5. Troubleshoot: This is where most failures occur. If it fails, check the logs. It is usually due to a legacy property editor you missed in Phase 1. Fix the issue in V7, restore the DB backup, and try again.

6. Once successful, log in to the V8 backoffice and verify your content tree exists.

Step 2b: The Modern Jumps (V8 -> V10 -> V13) Once your data is in V8 format, the hard part is over. The schemas for V8+ are much more aligned.

1. Create a fresh Umbraco v10 project. Point it to your now-V8 database and run it. The installer will quickly upgrade the schema.

2. Create a fresh Umbraco v13 project. Point it to your now-V10 database and run it. The final upgrade will complete.

You now have an Umbraco 13 site with all your content, media, and document types, but no working front-end template code.

Phase 3: The Code Rebuild (.NET Core)

This is the most time-consuming phase for developers. You must rewrite your custom code to adhere to .NET Core principles.

Key Changes:

• No web.config: Configuration moves to appsettings.json.

• Dependency Injection (DI): This is no longer optional; it is fundamental. You must inject services (like IUmbracoContextAccessor, IContentService) into your controllers instead of using static helpers like Umbraco.TypedContent.

• Controller Changes: SurfaceControllers and RenderMvcControllers have different base classes, namespaces, and return types (e.g., returning IActionResult instead of ActionResult).

• Views: Razor views will need updates, particularly switching from HTML helpers to Tag Helpers.

The image below illustrates the dramatic difference in coding style between a V7 controller and its V13 equivalent:

As seen on the right, the modern controller uses constructor injection to gain access to necessary services, resulting in cleaner, more testable code.

Conclusion

Migrating from Umbraco 7 to 13 is a significant undertaking that requires careful planning, a staged database upgrade, and a commitment to learning modern .NET practices. By following this step-by-step guide and utilizing the tools provided in Umbraco 7.15, you can successfully move your project to a secure, high-performance, and future-proof platform.