Edit

Share via

Breaking changes in .NET 8

  • Article
  • 04/10/2025

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.

ASP.NET Core

Title Type of change
ConcurrencyLimiterMiddleware is obsolete Source incompatible
Custom converters for serialization removed Behavioral change
ISystemClock is obsolete Source incompatible
Minimal APIs: IFormFile parameters require anti-forgery checks Behavioral change
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' package 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
Kerberos package removed from Alpine and Debian images Binary incompatible
'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
Complex.ToString format changed to <a; b> Behavioral change
Drive's current directory path enumeration Behavioral change
Enumerable.Sum throws new OverflowException for some inputs Behavioral change
FileStream writes when pipe is closed Behavioral change
FindSystemTimeZoneById doesn't return new object 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.WindowStyle honored when UseShellExecute is false Behavioral change
RuntimeIdentifier returns platform for which runtime was built Behavioral change
Type.GetType throws exception for all invalid element types 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
.NET Monitor only includes distroless images 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
Linux native library resolution no longer uses netcoredeps Behavioral change

Networking

Title Type of change
SendFile throws NotSupportedException for connectionless sockets Behavioral change
User info in mailto: URIs is compared 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
Duplicate output for -getItem, -getProperty, and -getTargetResult Behavioral change
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
Setting DebugSymbols to false disables PDB generation Behavioral change
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
.user file imported in outer builds 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
Certs checked before loading remote images in PictureBox Behavioral change
DateTimePicker.Text is empty string 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

Additional resources

Training

Learning path

Create cloud-native apps and services with .NET and ASP.NET Core - Training

Create independently deployable, highly scalable, and resilient apps and services using the free and open-source .NET platform. With .NET you can use popular microservice technology like Docker, Kubernetes, Dapr, Azure Container Registry, and more for .NET and ASP.NET Core applications and services.

Certification

Microsoft Certified: Azure Developer Associate - Certifications

Build end-to-end solutions in Microsoft Azure to create Azure Functions, implement and manage web apps, develop solutions utilizing Azure storage, and more.