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 Introduced
ConcurrencyLimiterMiddleware is obsolete Source incompatible Preview 4
Custom converters for serialization removed Behavioral change Preview 2
ISystemClock is obsolete Source incompatible Preview 5
Rate-limiting middleware requires AddRateLimiter Behavioral change Preview 5
Security token events return a JSonWebToken Behavioral change Preview 7
TrimMode defaults to full for Web SDK projects Source incompatible Preview 7

Containers

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

Core .NET libraries

Title Type of change Introduced
Activity operation name when null Behavioral change Preview 1
AnonymousPipeServerStream.Dispose behavior Behavioral change Preview 1
API obsoletions with custom diagnostic IDs Source incompatible Preview 1, 4
Backslash mapping in Unix file paths Behavioral change Preview 1
Base64.DecodeFromUtf8 methods ignore whitespace Behavioral change Preview 5
Boolean-backed enum type support removed Behavioral change Preview 1
FileStream writes when pipe is closed Behavioral change Preview 1
GC.GetGeneration might return Int32.MaxValue Behavioral change Preview 4
GetFolderPath behavior on Unix Behavioral change Preview 1
GetSystemVersion no longer returns ImageRuntimeVersion Behavioral change RC 1
IndexOfAnyValues renamed to SearchValues Source/binary incompatible Preview 5
ITypeDescriptorContext nullable annotations Source incompatible Preview 1
Legacy Console.ReadKey removed Behavioral change Preview 1
Method builders generate parameters with HasDefaultValue set to false Behavioral change Preview 5
Removed overloads of ToFrozenDictionary/ToFrozenSet Source/binary incompatible Preview 7
RuntimeIdentifier returns platform for which runtime was built Behavioral change RC 1

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 Introduced
Host determines RID-specific assets Binary incompatible/behavioral change Preview 5
StripSymbols defaults to true Behavioral change Preview 4

Entity Framework Core

Breaking changes in EF Core 8

Extensions

Title Type of change Introduced
ActivatorUtilities.CreateInstance behaves consistently Behavioral change Preview 1
ActivatorUtilities.CreateInstance requires non-null provider Behavioral change Preview 1
ConfigurationBinder throws for mismatched value Behavioral change Preview 1
ConfigurationManager package no longer references System.Security.Permissions Source incompatible Preview 3
DirectoryServices package no longer references System.Security.Permissions Source incompatible Preview 3
Empty keys added to dictionary by configuration binder Behavioral change Preview 5
HostApplicationBuilderSettings.Args respected by HostApplicationBuilder ctor Behavioral change Preview 2

Globalization

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

Interop

Title Type of change Introduced
CreateObjectFlags.Unwrap only unwraps on target instance Behavioral change Preview 5
Custom marshallers require additional members Source incompatible RC 1
IDispatchImplAttribute API is removed Binary incompatible Preview 6
SafeHandle types must have public constructor Source incompatible Preview 5

Reflection

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

SDK

Title Type of change Introduced
CLI console output uses UTF-8 Behavioral change/Source and binary incompatible Preview 1
Console encoding not UTF-8 after completion Behavioral change/Binary incompatible Preview 3
Containers default to use the 'latest' tag Behavioral change Preview 6
'dotnet pack' uses Release configuration Behavioral change/Source incompatible Preview 1
'dotnet publish' uses Release configuration Behavioral change/Source incompatible Preview 1
MSBuild custom derived build events deprecated Behavioral change RC 1
MSBuild respects DOTNET_CLI_UI_LANGUAGE Behavioral change Preview 5
Runtime-specific apps not self-contained Source/binary incompatible Preview 5
'dotnet restore' produces security vulnerability warnings Behavioral change Preview 4
SDK uses a smaller RID graph Behavioral change/Source incompatible RC 1
Trimming may not be used with .NET Standard or .NET Framework Behavioral change RC 1
Version requirements for .NET 8 SDK RC 1

Serialization

Title Type of change Introduced
BinaryFormatter disabled for most projects Behavioral change Preview 4
Reflection-based deserializer resolves metadata eagerly Behavioral change Preview 4

Windows Forms

Title Type of change Introduced
Anchor layout changes Behavioral change Preview 1
DefaultValueAttribute removed from some properties Behavioral change Preview 2
ExceptionCollection ctor throws ArgumentException Behavioral change Preview 1
Forms scale according to AutoScaleMode Behavioral change Preview 1
ImageList.ColorDepth default is Depth32Bit Behavioral change Preview 1
TableLayoutStyleCollection throws ArgumentException Behavioral change Preview 1
Top-level forms scale minimum and maximum size to DPI Behavioral change Preview 1
WFDEV002 obsoletion is now an error Source incompatible Preview 1

See also