Workik.

.NET 8 to .NET 10 Migration: An Enterprise Upgrade Guide

.NET 9 and .NET 10 Breaking Changes in Core Libraries

Fix .NET 9 and .NET 10 breaking changes in serialization, HTTP logging, BackgroundService, async LINQ and C# 14 when upgrading from .NET 8.

When you migrate from .NET 8 LTS (Long Term Support) to .NET 10 LTS, your application skips .NET 9 STS (Standard Term Support). This means your codebase encounters breaking changes introduced in both .NET 9 and .NET 10 at the same time. While many library updates are backward compatible, core behavior around serialization, HTTP logging, background task execution, and dependency injection changed across these two versions. Understanding these modifications prevents subtle production bugs that compiler warnings might not catch.

Previous lesson: Upgrade .NET 8 Projects to .NET 10: SDK, TFM and Packages | Next lesson: Upgrade ASP.NET Core 8 to ASP.NET Core 10


Upgrading Across Two Releases: The Compound Breaking Change Surface

Migrating across two major versions means you must check both the .NET 9 and .NET 10 breaking changes documentation. A library that worked without warnings on .NET 8 might break at runtime on .NET 10 because of intermediate shifts introduced in .NET 9.

Common runtime changes surface in three primary categories:

  • Serialization and data contracts: Hard blocks on legacy serializers and stricter duplicate property handling.
  • Networking and diagnostics: Automatic data redaction in request headers and query strings to improve default privacy.
  • Core hosting and collections: Threading behavior shifts in background hosts and type collisions in LINQ namespaces.

Common Mistake: Checking only the .NET 10 release notes. If you jump directly from .NET 8 to .NET 10, the runtime changes from .NET 9 apply to your application immediately.


Serialization and Reflection Changes

Complete Removal of BinaryFormatter

In .NET 9, BinaryFormatter implementation was fully disabled across all project types. If your code calls BinaryFormatter.Serialize or BinaryFormatter.Deserialize, the runtime throws a PlatformNotSupportedException. While an unsupported compatibility package exists, continuing to rely on it introduces security risks.

At Larkfield Insurance, legacy claim export files in Larkfield.Claims.Api previously used BinaryFormatter. You must migrate these models to System.Text.Json.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

System.Text.Json Checks Metadata Property Name Conflicts

In .NET 10, System.Text.Json checks that your property names do not clash with the metadata names it reserves for polymorphism and reference handling, such as $type, $id, $ref, or a custom type discriminator name. In .NET 8, a clash silently produced JSON with a duplicate property that could not be read back. In .NET 10, the serializer throws an InvalidOperationException the first time it builds the contract.

Before (.NET 8):

csharp
Copy

After (.NET 10):

csharp
Copy

Rename either the property or the discriminator, or mark the property with [JsonIgnore] if it should not be serialized.

XmlSerializer Now Serializes Obsolete Properties

In .NET 8, XmlSerializer treated properties marked [Obsolete] as if they had [XmlIgnore], so they never appeared in the XML output. In .NET 10, those properties are serialized like any other property. If a property is marked [Obsolete(IsError = true)], creating the serializer throws an InvalidOperationException.

If an integration partner relies on the old output, add [XmlIgnore] to the obsolete properties, or restore the old behavior with AppContext.SetSwitch("Switch.System.Xml.IgnoreObsoleteMembers", true);.


Networking, Diagnostics, and Security

Sensitive Data Redaction in Logging

In .NET 9 and .NET 10, diagnostics defaults favor security out of the box. HttpClientFactory now uses SocketsHttpHandler as its default primary handler and redacts potentially sensitive information.

  • Header values: every request and response header value is logged as * unless you call RedactLoggedHeaders to choose which headers to hide.
  • Query strings: URI (Uniform Resource Identifier) query parameters are replaced with * markers in built-in event sources and logger output.

If your troubleshooting workflows depend on viewing non-sensitive query keys in integration logs, you must configure logging explicitly instead of expecting raw URLs in output streams.

Trace Context Propagation

In .NET 10, the default trace context propagator conforms strictly to the W3C (World Wide Web Consortium) Trace Context standard. Outbound HTTP calls made by HttpClient format the traceparent and tracestate headers according to the latest specification. This avoids correlation dropouts when communicating across heterogeneous microservice meshes.

MailAddress Validation and Uri Limits

System.Net.Mail.MailAddress now rejects strings containing consecutive dots in the local part of an email address. If customer registration payloads in Larkfield.Portal submit addresses such as [email protected], parsing throws a FormatException. Ensure your upstream input validation catches this before passing values to system mail components.

Additionally, older maximum length limits on System.Uri strings have been lifted in .NET 10, allowing very long request paths without custom parsing routines.


Hosting and Background Execution

BackgroundService Start Behavior

In .NET 8, synchronous code placed at the start of a BackgroundService.ExecuteAsync method runs synchronously inside the host startup sequence. If a worker had long running synchronous initialization logic before the first await, it could delay the host from completing its initialization.

In .NET 10, BackgroundService runs all of ExecuteAsync on a background task, including the synchronous code before the first await. That code no longer delays host startup.

At Larkfield Insurance, Larkfield.Billing.Worker processes incoming payment records. Look at how this change affects execution:

Before (.NET 8):

csharp
Copy

In .NET 10, WarmUpPaymentCache() runs inside the spawned task. Host startup returns immediately. If your application depended on that blocking behavior to prevent incoming traffic before caches warmed up, you must move that logic into an implementation of IHostedLifecycleService or handle cache warming explicitly before calling app.RunAsync().

Named Mutexes on Unix

Starting in .NET 9 and continuing in .NET 10, named Mutex instances created on Unix operating systems default to user scope rather than system global scope. If you rely on a named mutex to synchronize processes across multiple operating system user accounts on Linux containers, you must use prefix namespaces or configure permissions accordingly.


Dependency Injection, Collections, and C# 14

System.Linq.AsyncEnumerable Namespace Collision

In .NET 10, LINQ operators for IAsyncEnumerable<T>, such as Where, Select, and ToListAsync, are built into the core libraries through the System.Linq.AsyncEnumerable class.

If your .NET 8 projects referenced the community System.Linq.Async package for those operators, building on .NET 10 can produce ambiguous call errors.

Pro Tip: Remove the System.Linq.Async package reference, or update it to version 7.0.0, which works with .NET 10. If a library still targets both .NET 8 and .NET 10, reference the System.Linq.AsyncEnumerable package instead.

Before (.NET 8 project file):

xml
Copy

After (.NET 10 project file):

xml
Copy

FromKeyedServices Attribute Fix

In early .NET 8 releases, if a parameter marked [FromKeyedServices("key")] had no keyed registration, the container silently injected the non-keyed registration of the same type. In .NET 9 and .NET 10, and in .NET 8 from patch 8.0.9 onward, the container throws an InvalidOperationException instead. Register the service with AddKeyedScoped, AddKeyedSingleton, or AddKeyedTransient.

C# 14 Overload Resolution with Spans

C# 14, which ships with .NET 10, adds implicit conversions from arrays to Span<T> and ReadOnlySpan<T>. As a result, a call such as statuses.Contains(status) on an array can now bind to the span-based MemoryExtensions.Contains instead of Enumerable.Contains.

In normal code this is faster and works the same. Inside expression trees that are compiled with interpretation, the span overload fails at runtime. If you build expression trees by hand, make the call bind to Enumerable explicitly:

csharp
Copy

Try It Yourself

Review your solution for code paths influenced by core library breaking changes:

  1. Scan for BinaryFormatter: Search your solution files for references to BinaryFormatter. Replace any remaining occurrences with System.Text.Json.
bash
Copy
  1. Search for AsyncEnumerable package usage: Run a check across all .csproj files for the System.Linq.Async package.
bash
Copy
  1. Validate Worker Startup: Inspect any class extending BackgroundService in your background processors, such as Larkfield.Billing.Worker. Check if any synchronous code at the beginning of ExecuteAsync is required to complete before the rest of the application starts accepting work. If it is, extract it into an IHostedService.StartAsync method.

  2. Inspect Keyed DI Registrations: Search for [FromKeyedServices] usages in your code. Ensure that every key queried by a constructor or parameter has a matching service registration configured in your dependency injection container.


In the next lesson, Upgrade ASP.NET Core 8 to ASP.NET Core 10, you will update web projects, switch to the built-in OpenAPI engine, and adjust authentication and endpoint routing.

Was this lesson helpful?