Breaking changes in .NET 8

If you're migrating an app to .NET 8, 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, or as a behavioral change:

• Binary incompatible - When run against the new runtime or component, existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.

• Source incompatible - When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.

• Behavioral change - Existing code and binaries may behave differently at run time. If the new behavior is undesirable, existing code would need to be updated and recompiled.

Note

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

ASP.NET Core

Title	Type of change
ConcurrencyLimiterMiddleware is obsolete	Source incompatible
Custom converters for serialization removed	Behavioral change
ISystemClock is obsolete	Source incompatible
Rate-limiting middleware requires AddRateLimiter	Behavioral change
Security token events return a JsonWebToken	Behavioral change
TrimMode defaults to full for Web SDK projects	Source incompatible

Containers

Title	Type of change
'ca-certificates' and 'krb5-libs' packages removed from Alpine images	Binary incompatible
Debian container images upgraded to Debian 12	Binary incompatible/behavioral change
Default ASP.NET Core port changed to 8080	Behavioral change
'libintl' package removed from Alpine images	Behavioral change
Multi-platform container tags are Linux-only	Behavioral change
New 'app' user in Linux images	Behavioral change

Core .NET libraries

Title	Type of change
Activity operation name when null	Behavioral change
AnonymousPipeServerStream.Dispose behavior	Behavioral change
API obsoletions with custom diagnostic IDs	Source incompatible
Backslash mapping in Unix file paths	Behavioral change
Base64.DecodeFromUtf8 methods ignore whitespace	Behavioral change
Boolean-backed enum type support removed	Behavioral change
Enumerable.Sum throws new OverflowException for some inputs	Behavioral change
FileStream writes when pipe is closed	Behavioral change
GC.GetGeneration might return Int32.MaxValue	Behavioral change
GetFolderPath behavior on Unix	Behavioral change
GetSystemVersion no longer returns ImageRuntimeVersion	Behavioral change
ITypeDescriptorContext nullable annotations	Source incompatible
Legacy Console.ReadKey removed	Behavioral change
Method builders generate parameters with HasDefaultValue set to false	Behavioral change
ProcessStartInfo.WindowsStyle honored when UseShellExecute is false	Behavioral change
RuntimeIdentifier returns platform for which runtime was built	Behavioral change

Cryptography

Title	Type of change	Introduced
AesGcm authentication tag size on macOS	Behavioral change	Preview 1
RSA.EncryptValue and RSA.DecryptValue obsolete	Source incompatible	Preview 1

Deployment

Title	Type of change
Host determines RID-specific assets	Binary incompatible/behavioral change
StripSymbols defaults to true	Behavioral change

Entity Framework Core

Breaking changes in EF Core 8

Extensions

Title	Type of change
ActivatorUtilities.CreateInstance behaves consistently	Behavioral change
ActivatorUtilities.CreateInstance requires non-null provider	Behavioral change
ConfigurationBinder throws for mismatched value	Behavioral change
ConfigurationManager package no longer references System.Security.Permissions	Source incompatible
DirectoryServices package no longer references System.Security.Permissions	Source incompatible
Empty keys added to dictionary by configuration binder	Behavioral change
HostApplicationBuilderSettings.Args respected by HostApplicationBuilder ctor	Behavioral change
ManagementDateTimeConverter.ToDateTime returns a local time	Behavioral change
System.Formats.Cbor DateTimeOffset formatting change	Behavioral change

Globalization

Title	Type of change
Date and time converters honor culture argument	Behavioral change
TwoDigitYearMax default is 2049	Behavioral change

Interop

Title	Type of change
CreateObjectFlags.Unwrap only unwraps on target instance	Behavioral change
Custom marshallers require additional members	Source incompatible
IDispatchImplAttribute API is removed	Binary incompatible
JSFunctionBinding implicit public default constructor removed	Binary incompatible
SafeHandle types must have public constructor	Source incompatible

Networking

Title	Type of change
SendFile throws NotSupportedException for connectionless sockets	Behavioral change

Reflection

Title	Type of change
IntPtr no longer used for function pointer types	Behavioral change

SDK

Title	Type of change
CLI console output uses UTF-8	Behavioral change/Source and binary incompatible
Console encoding not UTF-8 after completion	Behavioral change/Binary incompatible
Containers default to use the 'latest' tag	Behavioral change
'dotnet pack' uses Release configuration	Behavioral change/Source incompatible
'dotnet publish' uses Release configuration	Behavioral change/Source incompatible
Implicit using for System.Net.Http no longer added	Behavioral change/Source incompatible
MSBuild custom derived build events deprecated	Behavioral change
MSBuild respects DOTNET_CLI_UI_LANGUAGE	Behavioral change
Runtime-specific apps not self-contained	Source/binary incompatible
--arch option doesn't imply self-contained	Behavioral change
'dotnet restore' produces security vulnerability warnings	Behavioral change
SDK uses a smaller RID graph	Behavioral change/Source incompatible
Source Link included in the .NET SDK	Source incompatible
Trimming may not be used with .NET Standard or .NET Framework	Behavioral change
Unlisted packages not installed by default for .NET tools	Behavioral change
Version requirements for .NET 8 SDK	Source incompatible

Serialization

Title	Type of change
BinaryFormatter disabled for most projects	Behavioral change
PublishedTrimmed projects fail reflection-based serialization	Behavioral change
Reflection-based deserializer resolves metadata eagerly	Behavioral change

Windows Forms

Title	Type of change
Anchor layout changes	Behavioral change
DefaultValueAttribute removed from some properties	Behavioral change
ExceptionCollection ctor throws ArgumentException	Behavioral change
Forms scale according to AutoScaleMode	Behavioral change
ImageList.ColorDepth default is Depth32Bit	Behavioral change
System.Windows.Extensions doesn't reference System.Drawing.Common	Source incompatible
TableLayoutStyleCollection throws ArgumentException	Behavioral change
Top-level forms scale minimum and maximum size to DPI	Behavioral change
WFDEV002 obsoletion is now an error	Source incompatible

See also

• What's new in .NET 8