Umbraco 17 Upgrade Checklist for Umbraco 13 Sites

Use this Umbraco 17 upgrade checklist to assess your version 13 website, establish the work involved and confirm readiness before launch.

Start with checks 1–4 to investigate the existing build, upgrade route, packages and backoffice extensions. Use checks 5–10 to organise migration rehearsals, testing and release approval. Record an owner, status and supporting evidence for each area.

Umbraco 13 reaches end of life on 14 December 2026. Build the delivery timetable around the work your assessment identifies. For the wider architectural context, read our Umbraco 13 to 17 upgrade planning article.

What should you check before an Umbraco 17 upgrade?

Before upgrading, document the current build, choose an upgrade route, audit every package and review each AngularJS extension. Rehearse the content changes, confirm .NET 10 hosting, test integrations and let editors work through their daily tasks. Protect URLs, analytics and recovery steps before the release is approved.

1. Do you know what the site relies on today?

An estimate based on templates and package names will miss useful detail. Your review should cover the codebase, database, editorial work and production environment.

Record the following:

• Current Umbraco and .NET patch versions

• Installed packages, versions, licences and business use

• Custom property editors, dashboards, sections and menu items

• Content types, data types, compositions and validation rules

• Scheduled jobs, event handlers and background services

• Search indexes and Examine configuration

• Forms, members, authentication and permissions

• External APIs, payment services, CRM links and webhooks

• Hosting, storage, CDN, caching and deployment pipeline

• Redirects, canonical tags, XML sitemaps and robots rules

Our work across 100+ Umbraco websites has taught us to compare the technical inventory with the way editors publish. Code can say a feature exists, while an editor can tell you whether it earns a place in the new build.

Name an accountable person for every custom item and external service. Retire unused components before engineering begins, rather than paying to rebuild something nobody needs.

2. Which upgrade route fits the site?

Umbraco supports a direct LTS-to-LTS upgrade from version 13 to 17, with the intervening core migrations applied automatically. Review the breaking changes across versions 14–17 and update incompatible code, packages and backoffice extensions as required. A direct upgrade still needs a tested implementation and migration plan.

The second route begins with a fresh Umbraco 17 installation. Content and selected features can then be transferred after the new structure has been agreed. Umbraco describes both approaches in its guide to going from Umbraco 13 to 17.

A maintained build with limited custom code and compatible packages may suit the in-place route. Starting again on version 17 may suit an older codebase with abandoned packages, extensive backoffice extensions or a content model that editors find difficult to use.

Judge the two routes against:

• Engineering effort across the intervening breaking changes

• Content transfer and validation effort

• Package replacements and licence cost

• Editor training and acceptance testing

• Downtime, content freeze and recovery options

• Future maintenance effort

Choose the route after the inventory and package audit. A lower opening estimate can become expensive if it preserves weak content structures or obsolete extensions.

3. Have all packages been checked for Umbraco 17?

Every package needs one recorded outcome: upgrade, replace, rebuild or retire. A marketplace listing gives only part of the answer because production use may depend on configuration, stored data or custom code.

Review every package for:

• Explicit Umbraco 17 and .NET 10 support

• A maintained release history and named publisher

• Instructions for stored data

• Changes to configuration or editor behaviour

• Licence terms and renewal dates

• Security notices and known defects

• An exit option if maintenance ends

Package order also deserves attention. Umbraco advises upgrading products such as Forms or Deploy before upgrading the CMS package. Read the version notes for every commercial product before the first rehearsal.

Umbraco Forms needs a budget check because version 17 and later require a subscription licence. Agree the licence before approving the release estimate.

4. Which backoffice extensions need replacement?

AngularJS support left the backoffice in Umbraco 14. A property editor or dashboard built for the older backoffice cannot be copied into Umbraco 17 and expected to work.

Ask three questions about every extension:

1. Do editors use it during a normal publishing task?

2. Can a standard Umbraco 17 feature replace it?

3. Which data and editor behaviour must be preserved if custom development is needed?

Extensions that pass the review should use the current Web Components and Lit approach in Umbraco's extension documentation. Prototype high-use editors before building every screen. Test keyboard access, permissions, validation and error handling with the people who use them.

5. Has stored content survived a rehearsal?

Content can appear correct in the backoffice while the public page contains missing blocks, broken links or empty metadata. Testing needs to inspect both stored values and rendered pages.

Build a test set that includes:

• High-traffic landing pages

• Deeply nested pages

• Every block and property editor

• Empty, optional and legacy values

• Cropped images and focal points

• Internal links, external links and downloads

• Language variants and unpublished items

• Redirects, aliases and canonical URLs

• Forms and validation messages

Run the rehearsal against a recent production database copy that has been handled under the site's data policy. Compare record counts, published states, URLs, metadata and rendered HTML before approving the next test.

Sites that store member or form data need an extra review. Check retention periods, consent records, access permissions, audit logs and deletion rules against the organisation's GDPR duties.

6. Can the target platform run .NET 10?

Version 17 requires .NET 10. Check the build and production environments before application testing begins. The Umbraco 17 product page confirms the framework version and backoffice load balancing.

Verify these areas:

• .NET 10 in build and production environments

• Database engine and compatibility level

• File storage and media persistence

• Secrets, certificates and environment variables

• CDN and cache invalidation

• Health checks, logs, alerts and backups

• Deployment slots or equivalent release protection

• Backoffice access on every production instance

Multiple instances need another check because the backoffice can now run across several servers. Umbraco's backoffice load-balancing guide covers session affinity, SignalR, shared temporary files and distributed caches.

Test the chosen approach under production-like traffic. Record response time, error rate, cache behaviour and recovery time so the release has a baseline.

Version-specific checks for Umbraco 13 to 17

The upgrade crosses changes introduced in versions 14–17. Include these checks where the website uses the affected features.

For each applicable check, retain the expected result, test evidence and reviewer’s decision.

Consult the official breaking-change notes and upgrade-path guidance for implementation details.

Version-specific checks for Umbraco 13 to 17

The upgrade crosses changes introduced in versions 14–17. Include these checks where the website uses the affected features.

For each applicable check, retain the expected result, test evidence and reviewer’s decision.

Consult the official breaking-change notes and upgrade-path guidance for implementation details.

7. Have integrations passed failure testing?

A successful request proves the happy path. Each integration also needs expired credentials, slow responses, duplicate events, invalid data and service outages tested before release.

Include:

• CRM and marketing platforms

• Search services

• Payment providers

• Identity providers

• Email and SMS services

• Product or inventory feeds

• Analytics and consent tools

• Webhooks and scheduled imports

Record the expected response, retry policy, alert path and recovery step for each failure case. Logs should provide enough context for diagnosis without exposing personal data or secrets.

Example: testing a website form and CRM integration

Adapt this example to the website’s agreed behaviour.

• Normal operation: Submit the form and confirm that the expected record reaches the correct destination.

• Failure case: Simulate an unavailable destination in the test environment.

• Expected response: Confirm the agreed user message, error recording and operational alert.

• Recovery: Check how the submission is recovered and how duplicate processing is handled.

• Evidence: Retain the test time, relevant record references, redacted logs and reviewer’s decision.

Apply the same structure to other integrations: expected behaviour, failure behaviour, recovery and evidence.

For a related delivery example, our NYC Votes case study describes work involving legacy content, custom indexing and Salesforce integration. That project moved from Umbraco 8 to 13; a version 13-to-17 project requires its own assessment and testing.

8. Can editors complete their daily work?

Technical completion and editorial acceptance are separate checks. Give editors a staging site with migrated content and ask them to finish representative tasks without developer assistance.

Include these tasks:

• Create, preview, publish and unpublish a page

• Edit blocks, images, links and metadata

• Schedule publication and expiry

• Use language variants where applicable

• Review validation errors

• Restore content from history

• Submit and export form entries

• Use role-based permissions

Capture completion, errors and time spent. Fix failures in frequently used tasks before lower-value refinements, and keep the editor notes with the release record.

9. Will the release preserve search visibility?

Technical checks can pass while organic traffic falls because URLs, metadata or rendered HTML changed without review. Search protection belongs in the release acceptance criteria.

Before launch, compare the old and new site for:

• Status codes and indexable URLs

• Page titles and meta descriptions

• H1 headings and heading order

• Canonical tags and hreflang values

• Internal links and menus

• Structured data

• XML sitemaps and robots rules

• Image URLs and alternative text

• Open Graph and social metadata

• Redirect chains and broken links

Crawl both environments and compare templates at URL level. After launch, watch Google Search Console for indexing changes, page errors, query losses and unexpected URL growth.

10. Could the release be reversed safely?

A rollback plan needs named owners, tested commands and a time limit. A line in a launch document saying “restore the backup” gives too little guidance during an incident.

Release approval needs the following evidence:

• Database and media backups have been restored in rehearsal

• The previous application version can be deployed

• Database changes have an agreed recovery method

• DNS, CDN and cache steps are documented

• Content freeze rules are agreed

• Launch roles and contact details are current

• Go or no-go criteria are written

• Post-release checks have expected results

Run at least one timed rehearsal. Record how long recovery takes and which data could be lost during the reversal window.

Account for information created after the upgraded site goes live. New content, form submissions, member activity or transactions may need preservation or reconciliation if an earlier database is restored. Document how that information will be handled, who makes the recovery decision and how the recovered service will be checked.

Umbraco 17 readiness scorecard

Use this scorecard throughout the project. For each area, record a named owner, an evidence link and a status: open, approved or blocking.

During discovery, record findings and unresolved work. Before launch, approve each required area against its agreed acceptance criteria.

A completion percentage does not establish launch readiness. One unresolved issue affecting a required journey, content integrity, access control or recovery may prevent release.

Before launch, resolve mandatory open checks and blocking findings. Record the owner and decision for any accepted non-blocking issue.

What should happen after the assessment?

Turn each unresolved finding into a task with an owner, expected result and completion criteria. Use those tasks to agree the scope, budget and delivery timetable.

Before deployment, assign responsibility for production checks. Confirm important pages, forms, search, authentication and integrations on the live environment. Check scheduled publishing and background processes through their next relevant operating cycle.

If the upgrade cannot be completed before Umbraco 13 reaches end of life, review your Umbraco 13 XLTS options alongside the delivery plan.

For help assessing the findings, explore Phases’ Umbraco upgrade services to discuss your current build, proposed route and unresolved dependencies.