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
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:
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.
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):
csharpCopy
After (.NET 10):
csharpCopy
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):
csharpCopy
After (.NET 10):
csharpCopy
Rename either the property or the discriminator, or mark the property with [JsonIgnore] if it should not be serialized.
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);.
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.
* unless you call RedactLoggedHeaders to choose which headers to hide.* 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.
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.
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.
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):
csharpCopy
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().
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.
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):
xmlCopy
After (.NET 10 project file):
xmlCopy
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, 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:
csharpCopy
Review your solution for code paths influenced by core library breaking changes:
BinaryFormatter. Replace any remaining occurrences with System.Text.Json.bashCopy
.csproj files for the System.Linq.Async package.bashCopy
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.
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?