Edit

Breaking changes in .NET 7

  • Article
  • 4 minutes to read

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 indicates whether each breaking change is binary compatible or source compatible:

  • Binary compatible - Existing binaries will load and execute successfully without recompilation, and the run-time behavior won't change.
  • Source compatible - Source code will compile successfully without changes when targeting the new runtime or using the new SDK or component.

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
DateTime addition methods precision change ✔️ ✔️
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
Automatic RuntimeIdentifier for publish only ❌ ❌ 7.0.200
CLI console output uses UTF-8 ❌ ❌ 7.0.3xx
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
--output option no longer is valid for solution-level commands ❌ ❌ 7.0.200

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

See also