Breaking changes in .NET 7

If you're migrating an app to .NET 7, the breaking changes listed here might affect you. Changes are grouped by technology area, such as ASP.NET Core or Windows Forms.

This article categorizes each breaking change as binary incompatible or source incompatible:

  • Binary incompatible - Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, or different run-time behavior.
  • Source incompatible - Source code may encounter a breaking change in behavior when targeting the new runtime or using the new SDK or component. Behavior changes can include compile errors or different run-time behavior.

Note

This article is a work in progress. It's not a complete list of breaking changes in .NET 7. To query breaking changes that are still pending publication, see Issues of .NET.

ASP.NET Core

Title Binary compatible Source compatible Introduced
API controller actions try to infer parameters from DI ✔️ Preview 2
ASPNET-prefixed environment variable precedence ✔️ ✔️ Preview 3
AuthenticateAsync for remote auth providers ✔️ RC 1
Authentication in WebAssembly apps ✔️ RC 1
Default authentication scheme ✔️ Preview 7
Event IDs for some Microsoft.AspNetCore.Mvc.Core log messages changed ✔️ Preview 3
Fallback file endpoints ✔️ RC 2
IHubClients and IHubCallerClients hide members ✔️
Kestrel: Default HTTPS binding removed ✔️ Preview 6
Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv and libuv.dll removed Preview 1
Microsoft.Data.SqlClient updated to 4.0.1 ✔️ Preview 2
Middleware no longer defers to endpoint with null request delegate ✔️ Preview 7
MVC's detection of an empty body in model binding changed ✔️ Preview 3
Output caching API changes RC 2
SignalR Hub methods try to resolve parameters from DI ✔️ Preview 2

Core .NET libraries

Title Binary compatible Source compatible Introduced
API obsoletions with default diagnostic ID ✔️ Preview 3
API obsoletions with non-default diagnostic IDs ✔️ Preview 1
BinaryFormatter serialization APIs produce compiler errors ✔️ RC 1
BrotliStream no longer allows undefined CompressionLevel values ✔️
C++/CLI projects in Visual Studio ✔️ Preview 3
Changes to reflection invoke API exceptions ✔️ Preview 4
Collectible Assembly in non-collectible AssemblyLoadContext ✔️ Preview 5
Equals method behavior change for NaN ✔️ Preview 5
Generic type constraint on PatternContext<T> Preview 3
Legacy FileStream strategy removed ✔️ Preview 1
Library support for older frameworks Preview 1
Maximum precision for numeric format strings ✔️ RC 1
SerializationFormat.Binary is obsolete Preview 2
System.Runtime.CompilerServices.Unsafe NuGet package ✔️ ✔️ Preview 3
Time fields on symbolic links ✔️ Preview 1
Tracking linked cache entries ✔️ Preview 1
Validate CompressionLevel for BrotliStream ✔️ Preview 1

Configuration

Title Binary compatible Source compatible Introduced
System.diagnostics entry in app.config ✔️ RC 1

Cryptography

Title Binary compatible Source compatible Introduced
Decrypting EnvelopedCms doesn't double unwrap ✔️ Preview 5
Dynamic X509ChainPolicy verification time ✔️ Preview 7
X500DistinguishedName parsing of friendly names ✔️ Preview 5

Deployment

Title Binary compatible Source compatible Introduced
All assemblies trimmed by default ✔️ Preview 7
Multi-level lookup is disabled ✔️ Preview 4
x86 host path on 64-bit Windows ✔️ ✔️ Preview 6
TrimmerDefaultAction is deprecated ✔️ Preview 7

Extensions

Title Binary compatible Source compatible Introduced
ContentRootPath for apps launched by Windows Shell ✔️ Preview 6
Environment variable prefixes ✔️ Preview 4

Globalization

Title Binary compatible Source compatible Introduced
Globalization APIs use ICU libraries on Windows Server ✔️ RC 1

Interop

Title Binary compatible Source compatible Introduced
RuntimeInformation.OSArchitecture under emulation ✔️ RC 1

.NET MAUI

Title Binary compatible Source compatible
Constructors accept base interface instead of concrete type ✔️
Flow direction helper methods removed
New UpdateBackground parameter ✔️
ScrollToRequest property renamed
Some Windows APIs are removed

Networking

Title Binary compatible Source compatible Introduced
AllowRenegotiation default is false Preview 3
Custom ping payloads on Linux ✔️ Preview 2
Socket.End methods don't throw ObjectDisposedException ✔️ Preview 7

SDK and MSBuild

Title Binary compatible Source compatible Introduced
Automatic RuntimeIdentifier for certain projects ✔️ 7.0.100
MSBuild serialization of custom types in .NET 7 7.0.100
Side-by-side SDK installations 7.0.100
Version requirements for .NET 7 SDK ✔️ ✔️ 7.0.100
dotnet test: switch -a to alias --arch instead of --test-adapter-path Preview 1
dotnet test: switch -r to alias --runtime instead of --results-dir Preview 1

Serialization

Title Binary compatible Source compatible Introduced
DataContractSerializer retains sign when deserializing -0 ✔️ RC 1
Deserialize Version type with leading or trailing whitespace ✔️ Preview 1
JsonSerializerOptions copy constructor includes JsonSerializerContext ✔️ Preview 7
Polymorphic serialization for object types ✔️ RC 1
System.Text.Json source generator fallback ✔️ Preview 7

Windows Forms

Title Binary compatible Source compatible Introduced
Obsoletions and warnings ✔️ Preview 1 and RC 1
Some APIs throw ArgumentNullException ✔️ Preview 1

XML and XSLT

Title Binary compatible Source compatible Introduced
XmlSecureResolver is obsolete RC 1