Search code examples
c#asp.net-core.net-coreentity-framework-coreblazor

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

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

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

Solution

  • 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

    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
    • 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

    Checklist for v7

    5. Post-upgrade

    Checklist for v8

    5. Post-upgrade