Breaking changes in .NET 6

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 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 6. To query breaking changes that are still pending publication, see Issues of .NET.

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