Upgrade checklist for latest .NET, ASP.NET Core and EF Core

Question

I'm upgrading .NET, ASP.NET Core and EF Core to the latest versions.

Is there a comprehensive migration "checklist" I can follow?

Answer 1

General checklist for any version

1. Preparation

• If you're upgrading a non-trivial production system, ensure you have a few days to spare
• Make a list of all your third-party libraries (nugets), and visit their repos. Ensure each one supports the latest framework version - if not, then you 1) cannot upgrade yet, or 2) must find replacements for those not yet compatible with the latest framework.
• Consider your support requirements: v6 LTS (until 2024-11-12), v7 (until 2024-05-14), v8 LTS (until 2026-11-10)

2. Research

• Review announcements
  • .NET: v6, v7, v8
  • C#: v10 (.NET6), v11 (.NET7), v12 (.NET8)
  • ASP.NET Core: v6, v7, v8
  • EF Core: v7, v8
• Review release notes
  • .NET: v5, v6, v7, v8
  • C#: v9, v10, v11, v12
  • ASP.NET Core: v5, v6, v7, v8
  • EF Core: v5, v6, v7, v8
• Review breaking changes
  • .NET: v5, v6, v7, v8
  • C#: overview, v9, v10, v11, v12
  • ASP.NET Core: v5, v6, v7, v8
  • EF Core: v5, v6, v7, v8
• Review migration guides: v5, v6, v7, v8

3. Pre-upgrade

• Run all tests: important to take a baseline before upgrading, to be able to compare before/after. Take note of failing tests, if any (so they can be ignored later).
• Consider using the Upgrade Assistant for an idea of the work to be done
• Possibly remove old SDKs and runtimes
• Install SDK: v5, v6 LTS, v7, v8 LTS

4. Upgrade

• Checkout new git branch
• Update SDK version in global.json (if necessary): v6, v7, v8
• Update MyProject.csproj (and/or Directory.Build.props, if necessary)
  • Update framework: <TargetFramework>net8.0</TargetFramework>
  • Update language version (if necessary): <LangVersion>12.0</LangVersion>
• Update packages named Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.* and Microsoft.Extensions.*
• Update other dependencies, only if necessary (to reduce this upgrade's complexity). Update libraries which have been updated for the new framework version, as well as those that must be updated, e.g. non-Microsoft database providers.
• Update relevant dotnet tools, if necessary (in dotnet-tools.json, or those installed globally)
• Perform a smoke test for quick feedback: determine whether the system compiles and runs, perform simple ad-hoc testing, and watch for exceptions
• Handle breaking changes
  • Fix broken code
  • Fix broken tests; ignore failing tests which were already broken before the migration (fix them later)
• Remove obsolete workarounds. Find those workarounds that are no longer necessary due to changes/fixes in the latest framework. Typically those you've (hopefully) noted with something like // workaround: will be fixed in v6.
• Add new Roslyn analysers to .editorconfig: v5, v6, v7, v8
• Rerun tests, and compare to baseline
• Update documentation
  • Update relevant project documentation
  • Search for and update version-specific links, if necessary, e.g. links to learn.microsoft.com often have a version number like &view=aspnetcore-6.0 when there could be behaviour changes between versions
• Commit the git branch

5. Post-upgrade

• Perform tasks necessary to satisfy your continuous integration system, if appropriate
  • For dotnet, dotnet/sdk, dotnet/aspnet, dotnet/runtime, dotnet/runtime-deps docker images, update Dockerfile (FROM), compose files and scripts to new version
• Adopt new features, if necessary and/or desired. Most new framework features are optional, so only adopt them if you really want them.
• Refactor code to take advantage of various improvements; see what interests you in various links above.
• If this checklist helped you, upvote my question and answer ;-)

---

Checklist for v6

5. Post-upgrade

• Adopt major new features, optional
  • Refactor for global using directives
  • Refactor for file-scoped namespaces
    • Easiest to do with dotnet format: example
    • Also add new analysers to .editorconfig: csharp_style_namespace_declarations = file_scoped:suggestion and dotnet_diagnostic.IDE0161.severity = warning
  • Refactor for new minimal hosting model, by merging Program.cs and Startup.cs
  • Refactor for minimal APIs

---

Checklist for v7

5. Post-upgrade

• Adopt major new features, optional
  • Adopt rate limiting middleware
  • Use new "publish to container" feature

---

Checklist for v8

5. Post-upgrade

• Adopt major new features, optional
  • Deploy your app as native AOT
  • Blazor improvements include server-side rendering
  • Use EF's Complex Types for reusable value objects