.net made easy[]

How to Upgrade a Project to .NET 11: Step-by-Step Checklist

IntermediateLesson 311 of 325·Production .NET·16 min read·Updated

A new .NET version is out and your project still targets the old one. Here's how to move it across safely, in small steps you can check and undo.

The word upgrade makes many developers nervous. They imagine a weekend of red error messages. For most projects, moving to a new .NET version is much calmer than that: you change one line in the project file, update a few packages, rebuild, and run your tests.

The trouble usually comes from the places people forget: a global.json file that pins the old SDK, a Dockerfile that still pulls the old image, or a build pipeline that installs the old version. This lesson gives you a checklist that covers all of them.

In this lesson, you'll learn how to decide whether to upgrade, how to install and pin the .NET 11 SDK, how to retarget projects to net11.0, how to update NuGet packages, which breaking changes to check, and how to update Docker images and CI pipelines.

What Is It?

The Simple Explanation

Every .NET project says which version of .NET it's built for. Upgrading means changing that setting to the new version, then making sure everything around the project (packages, containers, build servers) uses the new version too.

Installing .NET 11 on your computer doesn't change any project by itself. A project moves only when you edit its <TargetFramework>.

The Technical Definition

Upgrading to .NET 11 means installing SDK 11.0.100 or later, changing each project's target framework moniker (TFM) to net11.0, updating framework-aligned packages (Microsoft.AspNetCore.*, Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.*) to 11.x, reviewing the .NET 11 breaking changes, and updating build and hosting environments: global.json, container base images and CI runners. Projects that target net11.0 compile as C# 15 by default.

Stay on .NET 10 for now

  • LTS: supported until 14 November 2028
  • Fine for apps that change rarely
  • Keeps C# 14 as the default language
  • No upgrade work today

Move to .NET 11

  • STS: also supported until 14 November 2028
  • C# 15: unions, closed hierarchies and more
  • Faster runtime and new APIs
  • Then plan the move to .NET 12 (LTS) in 2027

Why Does It Exist?

The Problem — Old Versions Stop Getting Fixes

Each .NET version is supported for a fixed time. After that it gets no more security patches. .NET 8 and .NET 9 both reached end of support on 10 November 2026, the same day .NET 11 was released. Apps still running on them keep working, but any security problem found from now on won't be fixed for them.

The Solution — A Routine, Repeatable Upgrade

Because a new version arrives every November, upgrading is a routine task, not a one-off project. A checklist makes it predictable: the same steps every year, done in an order where each step can be checked before you move on.

Big Picture

SDK
Install the .NET 11 SDK and update global.json if you have one
Projects
Change <TargetFramework> to net11.0
Packages
Update Microsoft packages to 11.x and remove ones now built in
Breaking changes
Read the list and test the areas your app uses
Containers and CI
Use 11.0 images and install 11.0.x on build servers
Tests
Build with zero new warnings and run every test

How It Works

THE UPGRADE CHECKLIST, IN ORDER
1. CHECK WHERE YOU ARE
  • Which SDKs are installed, which version each project targets, and whether a global.json pins an SDK.
▼
2. INSTALL AND PIN THE NEW SDK
  • Install the .NET 11 SDK, then update global.json so everyone on the team builds with it.
▼
3. RETARGET THE PROJECTS
  • Change <TargetFramework> to net11.0 in each project, or once in Directory.Build.props.
▼
4. UPDATE PACKAGES
  • Bring Microsoft packages to 11.x together and remove references to libraries that are now built in.
▼
5. BUILD AND READ THE WARNINGS
  • New warnings point at obsolete APIs and behavior changes. Fix them before going further.
▼
6. UPDATE CONTAINERS AND CI
  • Dockerfiles and pipelines must use .NET 11 too, or the app builds locally and fails on deploy.
▼
7. RUN ALL TESTS, THEN DEPLOY
  • Pay extra attention to the areas listed in the breaking changes.

Step 1 and 2: The SDK and global.json

Install the .NET 11 SDK (the same way as in lesson 4), then list the SDKs on your machine:

dotnet --list-sdks
10.0.100 [C:\Program Files\dotnet\sdk] 11.0.100 [C:\Program Files\dotnet\sdk]

Code → Meaning → Result: Your version numbers and folder may differ. Several SDKs can live side by side, and the newest one is used unless a global.json file says otherwise.

A global.json file in the repository root pins the SDK version so every developer and build server uses the same one. If your repository has one, update it:

{ "sdk": { "version": "11.0.100", "rollForward": "latestFeature" } }

rollForward: latestFeature allows any newer 11.0 SDK (for example a later patch) but never jumps to SDK 12. If you don't have a global.json, you don't need to create one.

Step 3: Retarget the Projects

Open each .csproj file and change the target framework:

<Project Sdk="Microsoft.NET.Sdk.Web"> <PropertyGroup> <TargetFramework>net11.0</TargetFramework> <!-- was net10.0 --> <Nullable>enable</Nullable> <ImplicitUsings>enable</ImplicitUsings> </PropertyGroup> </Project>

If the setting lives in a shared Directory.Build.props file, change it there once. A library that other apps use can support both versions while those apps catch up, by listing several targets (note the plural element name):

<TargetFrameworks>net10.0;net11.0</TargetFrameworks>

Step 4: Update the Packages

List the packages that have newer versions:

dotnet list package --outdated

Update the framework families together, so that every Microsoft.EntityFrameworkCore.* package has the same major version, and the same for Microsoft.AspNetCore.*:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer dotnet add package Microsoft.EntityFrameworkCore.Design

Code → Meaning → Result: Without --version, dotnet add package installs the latest stable version and updates the existing reference in your project file.

In .NET 11, nine common libraries moved into the framework itself, including Microsoft.Extensions.Logging.Abstractions, Microsoft.Extensions.Options and Microsoft.Extensions.DependencyInjection.Abstractions. If a net11.0 project still references one of them, the build shows warning NU1510. Delete that <PackageReference>; your code keeps working because the APIs are now built in.

Step 5: Build and Check the Breaking Changes

Run dotnet build and read every new warning. Then look through Microsoft's Breaking changes in .NET 11 page. Most entries affect specialised scenarios. These are the ones an ordinary app is most likely to notice:

Step 6: Containers and CI

This is the step people forget. Your laptop has .NET 11, but the Docker image and the build server don't. Update the image tags in your Dockerfile (see lesson 298):

FROM mcr.microsoft.com/dotnet/sdk:11.0 AS build WORKDIR /src COPY . . RUN dotnet publish -c Release -o /app FROM mcr.microsoft.com/dotnet/aspnet:11.0 WORKDIR /app COPY --from=build /app . ENTRYPOINT ["dotnet", "MyApi.dll"]

And the .NET version your pipeline installs, for example in GitHub Actions:

- uses: actions/setup-dotnet@v4 with: dotnet-version: '11.0.x'

Simple Example

Upgrading a small console app from .NET 10. Only one line of the project file changes:

<!-- Before --> <TargetFramework>net10.0</TargetFramework> <!-- After --> <TargetFramework>net11.0</TargetFramework>
dotnet build dotnet run

Code → Meaning → Result: The app builds and runs on .NET 11. Because it now targets net11.0, the compiler uses C# 15, so you can start using features such as union types and labeled break in this project.

Real-World Example

A team upgrades a web API with EF Core, Docker and GitHub Actions from .NET 10. They work on a branch, and each change is a separate commit so it can be reviewed and reverted on its own:

Analogy

Moving to a Renovated Kitchen

Upgrading .NET is like moving your restaurant's cooking into a renovated kitchen next door. Your recipes (your code) stay the same.

But you do have to check a few things: the ovens are newer and one or two settings behave differently (breaking changes), some ingredients you used to buy are now supplied by the kitchen (packages now built in), and the delivery drivers need the new address (Docker images and CI). Do all of that, and service continues as normal.

Under the Hood

Common Confusion

1. "Installing .NET 11 upgraded my projects" — no

Installing adds a new SDK next to the old ones. A project uses .NET 11 only after you change its <TargetFramework> to net11.0.

2. "STS means beta" — no

Standard Term Support releases are full, production-ready releases with the same quality bar as LTS. The only difference is how long they're supported.

3. "I have to upgrade everything at once" — no

Each project in a solution has its own target. You can upgrade an app while a shared library multi-targets net10.0;net11.0.

Common Mistakes

Mistake 1 — Forgetting the Dockerfile and the pipeline

The mistake: Retargeting to net11.0 and testing locally, but deploying with an image still based on aspnet:10.0. The app fails at start-up with "You must install or update .NET to run this application".

The fix: Search the repository for 10.0 and net10.0 (Dockerfiles, workflow files, global.json, scripts) and update them as part of the same change.

Mistake 2 — Mixing major versions of a package family

The mistake: Updating Microsoft.EntityFrameworkCore.SqlServer to 11.x but leaving Microsoft.EntityFrameworkCore.Design on 10.x, which causes version-conflict warnings or errors.

The fix: Update a whole family together. With many projects, Central Package Management (a Directory.Packages.props file) keeps versions in one place.

When Should I Use It?

Mental Model

SDK installed → global.json updated → <TargetFramework>net11.0</TargetFramework>.
Packages updated as families; built-in ones removed.
Build warnings fixed; breaking changes checked.
Dockerfile and CI moved to 11.0; all tests green; then deploy.

Remember: the project file decides the version, and everything around it must agree.

Key Takeaway


Check Your Understanding

Three questions to check you could upgrade a real project.

1. You installed the .NET 11 SDK, but your project still compiles as C# 14. Why?

Show answer

Correct: B

Why B is correct: The default C# version comes from the target framework. A net10.0 project uses C# 14 even when it's built with the .NET 11 SDK. Change the target to net11.0.

Why A is incorrect: The SDK can be installed correctly and still build net10.0 projects. The target decides the language version.

Why C is incorrect: The C# 15 compiler ships inside the .NET 11 SDK.

Why D is incorrect: The IDE isn't what decides the language version; the project's target framework is.

Reinforcement: Target framework → default C# version.

2. After upgrading, the app runs locally but the container fails to start with "You must install or update .NET to run this application". What's the most likely cause?

Show answer

Correct: C

Why C is correct: A net11.0 app needs the .NET 11 runtime. If the runtime image is still 10.0, the app can't start. Update the image tags to 11.0.

Why A is incorrect: The message is about a missing runtime, not a bug.

Why B is incorrect: A missing using is a compile error. It would never reach the container.

Why D is incorrect: A migration failure produces a database error, not a missing-runtime message.

Reinforcement: Update containers and CI together with the project.

3. After retargeting to net11.0, the build warns NU1510 about Microsoft.Extensions.Options. What should you do?

Show answer

Correct: A

Why A is correct: In .NET 11, Microsoft.Extensions.Options and eight other libraries are part of the framework, so the package reference is no longer needed.

Why B is incorrect: Downgrading undoes the upgrade. The warning has a simple fix.

Why C is incorrect: Suppressing everything hides useful warnings. Fix this one by removing the reference.

Why D is incorrect: An older version doesn't help; the library now ships with the framework.

Reinforcement: NU1510 on net11.0 = delete the reference; it's built in now.

That completes Part XIII. You know what's new in .NET 11 and C# 15 and how to bring a real project across. The final Part puts everything from the course together in the capstone, starting with designing an enterprise .NET application.