Breaking Changes in .NET 10: A Migration Guide from .NET 8

Breaking changes, dependency debt, and where the hours actually go for teams moving off .NET 8 or .NET 9.

.NET 8 and .NET 9 reach end of support on the same day: November 10, 2026. After that date, Microsoft stops providing security updates and technical support for both versions. That leaves most enterprise .NET teams with one practical destination. .NET 10, the current Long Term Support release, shipped November 11, 2025 and is supported through November 14, 2028.

The question that keeps coming up in sprint planning and architecture reviews is what the upgrade will actually take. This guide answers that in terms of effort rather than budget. It covers the breaking changes that matter in the 8 to 10 window, where dependency work tends to stall, what changes in your build pipeline, and what separates a two-day upgrade from a three-week one.

First, confirm which upgrade you’re doing

Teams often assume every move to .NET 10 is the same kind of project, and that assumption is where most estimates go wrong.

If you’re on .NET 8 or .NET 9, you’re moving within the modern .NET runtime. The architecture, SDK toolchain, and compilation model all stay the same. Microsoft designed the annual release cadence for incremental, low-disruption upgrades, and the move from .NET 8 to .NET 10 is a good example of that design working as intended.

If you’re on any version of .NET Framework, you’re facing a platform migration. That project carries a different risk profile and needs a different plan, which we cover at the end of this post. Everything in between assumes you’re starting from .NET 8 or .NET 9.

Key dates for your planning

.NET 9 was originally scheduled to reach end of support in May 2026. In September 2025, Microsoft extended Standard Term Support releases from 18 to 24 months, starting with .NET 9, which moved its end of support to November 10, 2026. Teams on .NET 9 now face the same deadline as teams on .NET 8.

If you go directly from .NET 8 to .NET 10, you inherit the breaking changes from .NET 9 as well as .NET 10, so plan to review both releases’ changes.

The short answer

For most applications on modern .NET, upgrading to .NET 10 takes less effort than teams budget for. The breaking changes in the 8 to 10 window are targeted and documented, and most of them show up as compiler warnings or analyzer diagnostics at build time. There’s no architectural rework and no wholesale change to the API surface, so most of the effort is mechanical.

The real uncertainty in your estimate comes from two places: test coverage and your dependency graph. Both are solvable, but that’s where surprises tend to appear.

Where the work goes

1. Breaking changes audit (2 to 8 hours)

Start with the breaking changes list below, then check Microsoft’s official lists for .NET 9 and .NET 10. ASP.NET Core and Entity Framework Core maintain their own lists, which are linked from those pages. For an LTS-to-LTS move, the changes are scoped to behavior in specific APIs rather than platform-wide rewrites.

Before you review anything manually, build against the .NET 10 SDK with warnings enabled. Obsoleted APIs surface as SYSLIB diagnostics, and those warnings narrow the list quickly.

For an average application, the audit takes an afternoon. A large but well-structured codebase might take a full day.

2. NuGet dependency compatibility sweep (4 to 16 hours)

This is where teams most consistently underestimate effort, so it’s worth spending time here before the upgrade begins.

Your application code may compile cleanly against .NET 10, but your packages need to as well. Major ecosystem packages such as Entity Framework Core, Serilog, Polly, and Dapper typically ship updates timed to major .NET releases and rarely cause problems.

These are the issues that tend to slow teams down:

• Unmaintained packages. Any package without a release in the past 12 to 18 months is a flag. Check whether the maintainer is still active and whether a .NET 10 target framework moniker appears in recent releases.
• Version pins. If you’ve hard-pinned packages for stability, you may be pulling in versions that predate .NET 10 compatibility.
• Internal packages. Shared libraries your team publishes internally need their own target framework updates, either before or in parallel with the applications that consume them.
• Transitive dependencies. A package you depend on may itself depend on something incompatible. In .NET 10, dotnet restore audits transitive packages by default, so expect new warnings on your first restore.

A clean dependency graph with well-maintained packages takes about half a day. Significant dependency debt with abandoned packages can take a week or more, because some of those packages will need to be forked, replaced, or wrapped.

Finish the dependency audit before committing to a timeline, since it’s the most variable input in the estimate.

3. SDK and build pipeline updates (2 to 4 hours)

This step is mechanical, but it still needs time in the plan:

• Update global.json to pin the .NET 10 SDK version.
• Update <TargetFramework> or <TargetFrameworks> in each project file.
• Update Docker base images (for example, mcr.microsoft.com/dotnet/aspnet:10.0). The default .NET 10 images now use Ubuntu, so check any Dockerfile steps that assume Debian packages or paths.
• Update CI/CD pipeline definitions to use .NET 10 SDK images or runners.
• Update build scripts that reference SDK paths or version-specific binaries.

Projects rarely stall at this stage, but the hours still belong in the estimate.

4. Test suite validation (the variable that drives your estimate)

The hard part of this step is rarely the code changes. It’s building enough confidence to ship once those changes are made.

With strong, well-maintained test coverage, the process is straightforward. You update the target framework, run the suite, fix the few failures caused by breaking changes or package behavior, and ship. Teams with solid coverage have finished in about a day.

With thin coverage, you’re validating manually. That means QA cycles, regression testing against production data patterns, and finding issues that automated tests would normally catch. The .NET 10 upgrade doesn’t create these risks. They already existed, and the version change brings them to the surface.

Before you schedule the upgrade, run your test suite as it stands and check coverage on critical paths. If business logic coverage is below 60 to 70 percent, expect to spend more time on validation than on the upgrade itself. In that case, either improve coverage first or budget extra time for manual QA.

5. Optional: new feature adoption

.NET 10 ships meaningful improvements, including runtime performance gains, C# 14 language features, Blazor rendering enhancements, and expanded AOT compilation support.

Adopting these is a separate decision from the version upgrade. You can update your target framework, ship on .NET 10, and leave application logic untouched. Plan new language features, new APIs, and performance-focused refactoring as a second phase, so feature interest doesn’t inflate the upgrade estimate and upgrade pressure doesn’t rush feature planning.

Effort ranges

For a moderately complex application with clean architecture and reasonable test coverage:

The width of that range has little to do with .NET 10 itself. It reflects earlier investment, or the lack of it, in dependency hygiene and test infrastructure.

Comprehensive List of Breaking Changes

.NET 10 introduces breaking changes across various areas, primarily to improve performance, security, and consistency. These are documented officially and grouped by technology area below. Migrating from .NET 8 means addressing changes from both .NET 9 and .NET 10. This list includes updates from Preview 6, marked accordingly.

Containers

Core .NET Libraries

Extensions

Globalization

Cryptography

Interop

Networking

SDK and MSBuild

ASP.NET Core

Entity Framework Core (EF Core 10)

C# Compiler

Other areas like Windows Forms (e.g., obsolete APIs) may apply; check official docs for full details.

Code Migration Patterns

Migrating code involves common patterns to address breaking changes:

• Project File Updates: Change <TargetFramework>net8.0</TargetFramework> to <TargetFramework>net10.0</TargetFramework>. For multi-targeting, use <TargetFrameworks>net8.0;net10.0</TargetFrameworks>.
• Deprecated API Replacement:
  • Before (.NET 8): var activity = ActivitySource.StartActivity("Old");
  • After (.NET 10): Review and adapt to new behaviors, e.g., ensure W3C compliance: var activity = ActivitySource.StartActivity("New", kind: ActivityKind.Internal);
• Nullability and Validation Fixes:
  • Before: X509Certificate cert = new(key); (assuming non-null)
  • After: X509Certificate cert = new(key ?? throw new ArgumentNullException());
• Async/Streaming Adjustments:
  • For Blazor streaming: Add opt-out if sync needed: request.SetBrowserResponseStreamingEnabled(false);
• Time Zone Handling in EF Core:
  • Before: var dt = reader.GetDateTimeOffset(0); (local assumption)
  • After: Adjust for UTC: var dtUtc = reader.GetDateTimeOffset(0).ToUniversalTime();
• New in Preview 6 Examples:
  • For DriveInfo on Linux: Update checks like if (drive.DriveFormat == "ext4") to handle new accurate formats.
  • For OpenSSL on macOS: Switch to SecureTransport or equivalent: Use SSLProtocols without OpenSSL dependencies.
  • For single-file native libs: Use NativeLibrary.Load with explicit paths or bundle properly.
  • For revocation checks: Set SslClientAuthenticationOptions.RemoteCertificateValidationCallback to customize if Online mode causes issues.

Run dotnet build with warnings as errors to catch issues early.

Tool Support for Automated Migration

The .NET Upgrade Assistant is the primary tool for automating migrations. It's available as a Visual Studio extension or CLI (dotnet tool install -g upgrade-assistant).

• How to Use: Install via VS Marketplace or CLI. Right-click project in VS > "Upgrade" or run upgrade-assistant upgrade MyProject.csproj. Choose in-place, side-by-side, or incremental mode.
• Features: Analyzes code, updates project files, fixes incompatibilities, and generates reports. Supports ASP.NET, console apps, libraries, and more.
• For .NET 8 to .NET 10: Update the tool to the newest version for Preview 6 support. Combine with Roslyn analyzers for custom fixes.

Other tools include try-convert for partial rewrites.

Common Pitfalls and How to Avoid Them

Treating a clean build as a finished upgrade. Many changes in this window are behavioral, so code compiles and then behaves differently at runtime. Trace context propagation, signal handling, and SQLite date handling in EF Core all fall into this category. Integration tests that use real configuration and real payloads catch what the compiler can’t.

Discovering dependency problems mid-upgrade. Run the dependency audit and dotnet list package --outdated before scheduling the work, and confirm that every package on your critical path ships a .NET 10 compatible version.

Testing on only one platform. The Ubuntu container image change, Linux filesystem reporting, and the removal of OpenSSL support on macOS each affect cross-platform code differently. Run CI on every operating system you deploy to.

Upgrading a large solution all at once. For large solutions, upgrade shared libraries first, multi-target them during the transition, and move applications in waves. Each wave then has a smaller blast radius and a clearer rollback path.

Tooling for the Upgrade

Microsoft has officially deprecated .NET Upgrade Assistant and now points teams to the GitHub Copilot app modernization chat agent, included with Visual Studio 2026 and Visual Studio 2022 17.14.16 or later. The agent analyzes projects and dependencies, produces a step-by-step plan with automated code fixes, and commits each change so you can validate it or roll it back. It requires a paid GitHub Copilot subscription, which the older Upgrade Assistant did not. We covered the transition in more detail in What Happened to the .NET Upgrade Assistant?

For a .NET 8 to .NET 10 upgrade, the SDK does much of the work on its own. Build-time diagnostics, dotnet restore auditing, and your existing test suite will surface most issues without additional tooling.

Should You Wait for .NET 11?

.NET 11 is expected in November 2026 as a Standard Term Support release. Under the 24-month STS policy, its support is projected to end around November 2028, about when .NET 10’s support also ends. Waiting for .NET 11 would add no runway. It would put you on a brand-new release, and it would leave .NET 8 or .NET 9 unpatched while you wait.

For most enterprise teams, .NET 10 is the right target now. .NET 11 features can be evaluated later, separately from this deadline.

If You’re on .NET Framework, This Is a Different Project

If the effort estimates above felt like a relief, that’s the modern .NET versioning model working as designed.

Many teams asking what a .NET 10 upgrade costs are actually running .NET Framework and hoping for a similar answer. Moving from .NET Framework to modern .NET is a platform migration. It involves a different runtime, a different hosting model, a different deployment story, and, in most cases, a different API surface that requires application-level changes. Applications that depend on WebForms or WCF, and older applications built on VB6 or PowerBuilder, often have no supported path forward without specialized help. That effort starts at weeks and scales with application size and complexity.

For those teams, the .NET 10 upgrade timeline isn’t the constraint. The modernization roadmap is, and it’s worth planning before the November deadline.

Frequently Asked Questions

When does .NET 8 support end?
November 10, 2026. .NET 9 reaches end of support on the same date.

Can I skip .NET 9 and upgrade straight from .NET 8 to .NET 10?
Yes, and most teams do. Review the breaking changes for both .NET 9 and .NET 10, because skipping a version means inheriting its changes.

How long does a .NET 8 to .NET 10 upgrade take?
For a moderately complex application, anywhere from one or two days to about three weeks. The range depends mostly on dependency health and test coverage, not on .NET 10 itself.

What replaced the .NET Upgrade Assistant?
Microsoft now recommends the GitHub Copilot app modernization chat agent in Visual Studio, which requires a GitHub Copilot subscription.

Is upgrading from .NET Framework the same as upgrading from .NET 8?
No. .NET Framework to modern .NET is a platform migration with a different runtime and API surface, and it typically requires application-level changes.