Breaking changes in .NET 6

Article
03/18/2023

If you're migrating an app to .NET 6, 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.

ASP.NET Core

Title	Binary compatible	Source compatible	Introduced
ActionResult<T> sets StatusCode to 200	✔️	❌
AddDataAnnotationsValidation method made obsolete	✔️	❌
Assemblies removed from Microsoft.AspNetCore.App shared framework	❌	✔️
Blazor: Parameter name changed in RequestImageFileAsync method	✔️	❌	Preview 1
Blazor: WebEventDescriptor.EventArgsType property replaced	❌	❌
Blazor: Byte array interop	✔️	❌	Preview 6
Changed MessagePack library in @microsoft/signalr-protocol-msgpack	❌	✔️
ClientCertificate property doesn't trigger renegotiation for HttpSys	✔️	❌
EndpointName metadata not set automatically	✔️	❌	RC 2
Identity: Default Bootstrap version of UI changed	❌	❌
Kestrel: Log message attributes changed	✔️	❌
Microsoft.AspNetCore.Http.Features split	❌	✔️
Middleware: HTTPS Redirection Middleware throws exception on ambiguous HTTPS ports	✔️	❌
Middleware: New Use overload	✔️	❌	Preview 4
Minimal API renames in RC 1	❌	❌	RC 1
Minimal API renames in RC 2	❌	❌	RC 2
MVC doesn't buffer IAsyncEnumerable types when using System.Text.Json	✔️	❌	Preview 4
Nullable reference type annotations changed	✔️	❌
Obsoleted and removed APIs	✔️	❌	Preview 1
PreserveCompilationContext not configured by default	❌	✔️
Razor: Compiler no longer produces a Views assembly	✔️	❌	Preview 3
Razor: Logging ID changes	❌	✔️	RC1
Razor: RazorEngine APIs marked obsolete	✔️	❌	Preview 1
SignalR: Java Client updated to RxJava3	❌	✔️	Preview 4
TryParse and BindAsync methods are validated	❌	❌	RC 2

Containers

Title	Binary compatible	Source compatible	Introduced
Default console logger formatting in container images	✔️	❌	Servicing 6.0.6

For information on other breaking changes for containers in .NET 6, see .NET 6 Container Release Notes.

Core .NET libraries

Title	Binary compatible	Source compatible	Introduced
API obsoletions with non-default diagnostic IDs	✔️	❌	Preview 1
Changes to nullable reference type annotations	✔️	❌	Preview 1-2
Conditional string evaluation in Debug methods	✔️	❌	RC 1
Environment.ProcessorCount behavior on Windows	✔️	❌	Preview 2
File.Replace on Unix throws exceptions to match Windows	✔️	❌	Preview 7
FileStream locks files with shared lock on Unix	❌	✔️	Preview 1
FileStream no longer synchronizes file offset with OS	❌	❌	Preview 4
FileStream.Position updates after ReadAsync or WriteAsync completes	❌	❌	Preview 4
New diagnostic IDs for obsoleted APIs	✔️	❌	Preview 5
New nullable annotation in AssociatedMetadataTypeTypeDescriptionProvider	✔️	❌	RC 2
New System.Linq.Queryable method overloads	✔️	❌	Preview 3-4
Older framework versions dropped from package	❌	✔️	Preview 5
Parameter names changed	✔️	❌	Preview 1
Parameter names in Stream-derived types	✔️	❌	Preview 1
Partial and zero-byte reads in DeflateStream, GZipStream, and CryptoStream	✔️	❌	Preview 6
Set timestamp on read-only file on Windows	❌	✔️	Servicing 6.0.2
Standard numeric format parsing precision	✔️	❌	Preview 2
Static abstract members in interfaces	❌	✔️	Preview 7
StringBuilder.Append overloads and evaluation order	❌	✔️	RC 1
Strong-name APIs throw PlatformNotSupportedException	❌	✔️	Preview 4
System.Drawing.Common only supported on Windows	❌	❌	Preview 7
System.Security.SecurityContext is marked obsolete	✔️	❌	RC 1
Task.FromResult may return singleton	❌	✔️	Preview 1
Unhandled exceptions from a BackgroundService	✔️	❌	Preview 4

Cryptography

Title	Binary compatible	Source compatible	Introduced
CreateEncryptor methods throw exception for incorrect feedback size	❌	✔️	Preview 7

Deployment

Title	Binary compatible	Source compatible	Introduced
x86 host path on 64-bit Windows	✔️	✔️	Servicing release

Entity Framework Core

Breaking changes in EF Core 6

Extensions

Title	Binary compatible	Source compatible	Introduced
AddProvider checks for non-null provider	✔️	❌	RC 1
FileConfigurationProvider.Load throws InvalidDataException	✔️	❌	RC 1
Repeated XML elements include index	❌	✔️
Resolving disposed ServiceProvider throws exception	✔️	❌	RC 1

Globalization

Title	Binary compatible	Source compatible	Introduced
Culture creation and case mapping in globalization-invariant mode			Preview 7

Interop

Title	Binary compatible	Source compatible	Introduced
Static abstract members in interfaces	❌	✔️	Preview 7

JIT compiler

Title	Binary compatible	Source compatible	Introduced
Coerce call arguments according to ECMA-335	✔️	✔️	Preview 1

Networking

Title	Binary compatible	Source compatible	Introduced
Port removed from SPN for Kerberos and Negotiate	❌	✔️	RC 1
WebRequest, WebClient, and ServicePoint are obsolete	✔️	❌	Preview 1

SDK

Title	Binary compatible	Source compatible	Introduced
`-p` option for `dotnet run` is deprecated	✔️	❌	Preview 6
C# code in templates not supported by earlier versions	✔️	✔️	Preview 7
EditorConfig files implicitly included	✔️	❌
Generate apphost for macOS	✔️	❌	Preview 6
Generate error for duplicate files in publish output	❌	✔️	Preview 1
GetTargetFrameworkProperties and GetNearestTargetFramework removed from ProjectReference protocol	❌	✔️	Preview 1
Install location for x64 emulated on Arm64	✔️	❌	RC 2
MSBuild no longer supports calling GetType()			RC 1
OutputType not automatically set to WinExe	✔️	❌	RC 1
Publish ReadyToRun with --no-restore requires changes	✔️	❌	6.0.100
runtimeconfig.dev.json file not generated	❌	✔️	6.0.100
RuntimeIdentifier warning if self-contained is unspecified	✔️	❌	RC 1
Version requirements for .NET 6 SDK	✔️	✔️	6.0.300
.version file includes build version	✔️	✔️	6.0.401
Write reference assemblies to IntermediateOutputPath	❌	✔️	6.0.200

Serialization

Title	Binary compatible	Source compatible	Introduced
DataContractSerializer retains sign when deserializing -0	❌	✔️	Servicing 6.0.11
Default serialization format for TimeSpan	❌	✔️	Servicing 6.0.2
IAsyncEnumerable serialization	✔️	❌	Preview 4
JSON source-generation API refactoring	❌	✔️	RC 2
JsonNumberHandlingAttribute on collection properties	❌	✔️	RC 1
New JsonSerializer source generator overloads	❌	✔️	Preview 6

Windows Forms

Title	Binary compatible	Source compatible	Introduced
C# templates use application bootstrap	✔️	❌	RC 1
Selected TableLayoutSettings properties throw InvalidEnumArgumentException	❌	✔️	Preview 1
DataGridView-related APIs now throw InvalidOperationException	❌	✔️	Preview 4
ListViewGroupCollection methods throw new InvalidOperationException	❌	✔️	RC 2
NotifyIcon.Text maximum text length increased	❌	✔️	Preview 1
ScaleControl called only when needed	✔️	❌	Servicing 6.0.101
Some APIs throw ArgumentNullException	❌	✔️	Preview 1-4
TreeNodeCollection.Item throws exception if node is assigned elsewhere	❌	✔️	Preview 1

XML and XSLT

Title	Binary compatible	Source compatible	Introduced
XmlDocument.XmlResolver nullability change	❌	✔️	RC 1
XNodeReader.GetAttribute behavior for invalid index	✔️	❌	Preview 2