How to Upgrade a Project to .NET 11: Step-by-Step Checklist
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
How It Works
- Which SDKs are installed, which version each project targets, and whether a global.json pins an SDK.
- Install the .NET 11 SDK, then update global.json so everyone on the team builds with it.
- Change <TargetFramework> to net11.0 in each project, or once in Directory.Build.props.
- Bring Microsoft packages to 11.x together and remove references to libraries that are now built in.
- New warnings point at obsolete APIs and behavior changes. Fix them before going further.
- Dockerfiles and pipelines must use .NET 11 too, or the app builds locally and fails on 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-sdks10.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 --outdatedUpdate 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.DesignCode → 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:
- Newer CPUs required on Intel/AMD. .NET 11 needs an x86-64-v2 processor. Every x86/x64 CPU that Windows 11 supports qualifies; only very old chips, out of Intel and AMD support since around 2013, don't. Arm64 requirements didn't change.
- **A crashing BackgroundService now fails the app.** If a hosted background service throws, host.RunAsync() now throws too, and the app exits with a failure code instead of reporting success.
- Corrupted ZIP files are detected. Reading a ZIP entry now checks its CRC32 checksum and throws InvalidDataException if the data is damaged.
- **Math.Round is now correctly rounded.** For example, Math.Round(655.925, 2, MidpointRounding.AwayFromZero) now returns 655.92, because the double 655.925 is actually stored as slightly less than 655.925. For money, use decimal.
- **DateOnly.TryParse and TimeOnly.TryParse throw for invalid styles or formats.** Passing a nonsense DateTimeStyles value or format specifier now throws ArgumentException instead of returning false. Ordinary bad input text still returns false.
- EF Core 11 uses Microsoft.Data.SqlClient 7.0, defaults to SQL Server compatibility level 160 and throws when it finds no migrations to apply (see lesson 355).
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 runCode → 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:
- Commit 1: global.json → 11.0.100; Directory.Build.props → net11.0.
- Commit 2: ASP.NET Core and EF Core packages → 11.x; removed Microsoft.Extensions.Options (NU1510).
- Commit 3: fixed two new obsolete-API warnings shown by the build.
- Commit 4: Dockerfile → sdk:11.0 and aspnet:11.0; workflow → dotnet-version: '11.0.x'.
- Then: all tests pass in CI, the branch is deployed to a test environment, checked, and released.
Analogy
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
- SDK and runtime are different things. The SDK builds your code; the runtime runs it. The .NET 11 SDK can still build net10.0 projects, which keep C# 14 as their default language. A server only needs the runtime, which the aspnet:11.0 image already contains.
- Why a missing runtime fails at start-up. A normal (framework-dependent) app needs the matching runtime on the machine. If only .NET 10 is installed, starting a net11.0 app prints "You must install or update .NET to run this application".
- **C# 15 is tied to net11.0.** The compiler chooses the default language version from the target framework. Forcing C# 15 on a net10.0 project with <LangVersion> isn't supported, because some features need the .NET 11 runtime and libraries.
- Support dates. .NET 10 (LTS) and .NET 11 (STS) are both supported until 14 November 2028. The next version, .NET 12, is planned as an LTS release in November 2027.
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?
- On .NET 8 or 9: upgrade now. They no longer receive security fixes. Moving to .NET 10 (LTS) or to .NET 11 (STS) is a good choice.
- On .NET 10: no rush; it's supported until November 2028. Upgrade when you want C# 15 or the .NET 11 improvements.
- Writing a library: multi-target net10.0;net11.0 so apps on either version can use it.
- Starting a new project today: target net11.0 unless your organisation requires LTS releases only.
Mental Model
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
- Installing the SDK changes nothing by itself; <TargetFramework>net11.0</TargetFramework> moves a project to .NET 11 and C# 15.
- Update global.json, then packages in families; remove references that now trigger NU1510.
- Read the breaking changes, especially CPU requirements, background-service failures, ZIP checksums and Math.Round.
- Update Docker images (sdk:11.0, aspnet:11.0) and CI (11.0.x) in the same change.
- .NET 8 and 9 are out of support; .NET 10 and 11 are both supported until November 2028.
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.