Edit

Breaking changes in .NET 5

  • Article

If you're migrating an app to .NET 5, the breaking changes listed here might affect you. Changes are grouped by technology area, such as ASP.NET Core or cryptography.

This article indicates whether each breaking change is binary compatible or source compatible:

  • Binary compatible - Existing binaries will load and execute successfully without recompilation, and the run-time behavior won't change.
  • Source compatible - Source code will compile successfully without changes when targeting the new runtime or using the new SDK or component.

ASP.NET Core

Title Binary compatible Source compatible
ASP.NET Core apps deserialize quoted numbers ✔️ ❌
AzureAD.UI and AzureADB2C.UI APIs obsolete ✔️ ❌
BinaryFormatter serialization methods are obsolete ✔️ ❌
Resource in endpoint routing is HttpContext ✔️ ❌
Microsoft-prefixed Azure integration packages removed ❌ ✔️
Blazor: Route precedence logic changed in Blazor apps ✔️ ❌
Blazor: Updated browser support ✔️ ✔️
Blazor: Insignificant whitespace trimmed by compiler ✔️ ❌
Blazor: JSObjectReference and JSInProcessObjectReference types are internal ✔️ ❌
Blazor: Target framework of NuGet packages changed ❌ ✔️
Blazor: ProtectedBrowserStorage feature moved to shared framework ✔️ ❌
Blazor: RenderTreeFrame readonly public fields are now properties ❌ ✔️
Blazor: Updated validation logic for static web assets ❌ ✔️
Cryptography APIs not supported on browser ❌ ✔️
Extensions: Package reference changes ❌ ✔️
Kestrel and IIS BadHttpRequestException types are obsolete ✔️ ❌
HttpClient instances created by IHttpClientFactory log integer status codes ✔️ ❌
HttpSys: Client certificate renegotiation disabled by default ✔️ ❌
IIS: UrlRewrite middleware query strings are preserved ✔️ ❌
Kestrel: Configuration changes detected by default ✔️ ❌
Kestrel: Default supported TLS protocol versions changed ✔️ ❌
Kestrel: HTTP/2 disabled over TLS on incompatible Windows versions ✔️ ✔️
Kestrel: Libuv transport marked as obsolete ✔️ ❌
Obsolete properties on ConsoleLoggerOptions ✔️ ❌
ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed ✔️ ❌
Pubternal APIs removed ✔️ ❌
Obsolete constructor removed in request localization middleware ✔️ ❌
Middleware: Database error page marked as obsolete ✔️ ❌
Exception handler middleware throws original exception ✔️ ✔️
ObjectModelValidator calls a new overload of Validate ✔️ ❌
Cookie name encoding removed ✔️ ❌
IdentityModel NuGet package versions updated ❌ ✔️
SignalR: MessagePack Hub Protocol options type changed ✔️ ❌
SignalR: MessagePack Hub Protocol moved ✔️ ❌
UseSignalR and UseConnections methods removed ✔️ ❌
CSV content type changed to standards-compliant ✔️ ❌

Code analysis

Title Binary compatible Source compatible
CA1416 warning ✔️ ❌
CA1417 warning ✔️ ❌
CA1831 warning ✔️ ❌
CA2013 warning ✔️ ❌
CA2014 warning ✔️ ❌
CA2015 warning ✔️ ❌
CA2200 warning ✔️ ❌
CA2247 warning ✔️ ❌

Core .NET libraries

Title Binary compatible Source compatible
Assembly-related API changes for single-file publishing ❌ ✔️
BinaryFormatter serialization methods are obsolete ✔️ ❌
Code access security APIs are obsolete ✔️ ❌
CreateCounterSetInstance throws InvalidOperationException ✔️ ❌
Default ActivityIdFormat is W3C ❌ ✔️
Environment.OSVersion returns the correct version ❌ ✔️
FrameworkDescription's value is .NET not .NET Core ✔️ ❌
GAC APIs are obsolete ✔️ ❌
Hardware intrinsic IsSupported checks ❌ ✔️
IntPtr and UIntPtr implement IFormattable ✔️ ❌
LastIndexOf handles empty search strings ❌ ✔️
URI paths with non-ASCII characters on Unix ❌ ✔️
API obsoletions with non-default diagnostic IDs ✔️ ❌
Obsolete properties on ConsoleLoggerOptions ✔️ ❌
Complexity of LINQ OrderBy.First ❌ ✔️
OSPlatform attributes renamed or removed ✔️ ❌
Microsoft.DotNet.PlatformAbstractions package removed ❌ ✔️
PrincipalPermissionAttribute is obsolete ✔️ ❌
Parameter name changes from preview versions ✔️ ❌
Parameter name changes in reference assemblies ✔️ ❌
Remoting APIs are obsolete ❌ ✔️
Order of Activity.Tags list is reversed ✔️ ❌
SSE and SSE2 comparison methods handle NaN ✔️ ❌
Thread.Abort is obsolete ✔️ ❌
Uri recognition of UNC paths on Unix ❌ ✔️
UTF-7 code paths are obsolete ✔️ ❌
Behavior change for Vector2.Lerp and Vector4.Lerp ✔️ ❌
Vector<T> throws NotSupportedException ❌ ✔️

Cryptography

Title Binary compatible Source compatible
Cryptography APIs not supported on browser ❌ ✔️
Cryptography.Oid is init-only ✔️ ❌
Default TLS cipher suites on Linux ❌ ✔️
Create() overloads on cryptographic abstractions are obsolete ✔️ ❌
Default FeedbackSize value changed ✔️ ❌

Entity Framework Core

Breaking changes in EF Core 5.0

Globalization

Title Binary compatible Source compatible
Use ICU libraries on Windows ❌ ✔️
StringInfo and TextElementEnumerator are UAX29-compliant ❌ ✔️
Unicode category changed for Latin-1 characters ✔️ ❌
TextInfo.ListSeparator values changed ✔️ ❌

Interop

Title Binary compatible Source compatible
Support for WinRT is removed ❌ ✔️
Casting RCW to InterfaceIsIInspectable throws exception ❌ ✔️
No A/W suffix probing on non-Windows platforms ❌ ✔️

Networking

Title Binary compatible Source compatible
Cookie path handling conforms to RFC 6265 ✔️ ❌
LocalEndPoint is updated after calling SendToAsync ✔️ ❌
MulticastOption.Group doesn't accept null ✔️ ❌
Streams allow successive Begin operations ❌ ✔️
WinHttpHandler removed from .NET runtime ❌ ✔️

SDK

Title Binary compatible Source compatible
Directory.Packages.props files imported by default ❌ ✔️
Error generated when executable project references mismatched executable ✔️
FrameworkReference replaced with WindowsSdkPackageVersion for Windows SDK ✔️ ❌
NETCOREAPP3_1 preprocessor symbol not defined ✔️ ❌
OutputType set to WinExe ❌ ✔️
PublishDepsFilePath behavior change ❌ ✔️
TargetFramework change from netcoreapp to net ❌ ✔️
WinForms and WPF apps use Microsoft.NET.Sdk ❌ ✔️

Security

Title Binary compatible Source compatible
Code access security APIs are obsolete ✔️ ❌
PrincipalPermissionAttribute is obsolete ✔️ ❌
UTF-7 code paths are obsolete ✔️ ❌

Serialization

Title Binary compatible Source compatible
BinaryFormatter.Deserialize rewraps exceptions ✔️ ❌
JsonSerializer.Deserialize requires single-character string ✔️ ❌
ASP.NET Core apps deserialize quoted numbers ✔️ ❌
JsonSerializer.Serialize throws ArgumentNullException ✔️ ❌
Non-public, parameterless constructors not used for deserialization ✔️ ❌
Options are honored when serializing key-value pairs ✔️ ❌

Windows Forms

Title Binary compatible Source compatible
Native code can't access Windows Forms objects ✔️ ❌
OutputType set to WinExe ❌ ✔️
DataGridView doesn't reset custom fonts ✔️ ❌
Methods throw ArgumentException ✔️ ❌
Methods throw ArgumentNullException ✔️ ❌
Properties throw ArgumentOutOfRangeException ✔️ ❌
TextFormatFlags.ModifyString is obsolete ✔️ ❌
DataGridView APIs throw InvalidOperationException ✔️ ❌
WinForms apps use Microsoft.NET.Sdk ❌ ✔️
Removed status bar controls ✔️ ❌

WPF

Title Binary compatible Source compatible
OutputType set to WinExe ❌ ✔️
WPF apps use Microsoft.NET.Sdk ❌ ✔️

See also