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
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
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
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
.NET feedback
The .NET documentation is open source. Provide feedback here.
Feedback
Submit and view feedback for