.NET 5 is here, and it's incredible! But... yes, there's a but. With all good things also come to some less good things. After all, it's impossible to make an omelet without breaking a few eggs, and .NET 5 is no exception. If you try to migrate from .NET Core 3.1 to .NET 5 you may run into a few breaking changes. Before jumping in with that migration and taking advantage of all the new features, make sure you have considered what may break first.
ASP.NET Core
- ASP.NET Core apps allow deserializing quoted numbers
- Authentication: AzureAD.UI and AzureADB2C.UI APIs and packages marked obsolete
- Authorization: Resource in endpoint routing is HttpContext
- Azure: Microsoft-prefixed Azure integration packages removed
- Blazor: Insignificant whitespace trimmed from components at compile time
- Blazor: JSObjectReference and JSInProcessObjectReference types changed to internal
- Blazor: ProtectedBrowserStorage feature moved to shared framework
- Blazor: RenderTreeFrame readonly public fields have become properties
- Blazor: Target framework of NuGet packages changed
- Blazor: Updated browser support
- Extensions: Package reference changes affecting some NuGet packages
- HTTP: HttpClient instances created by IHttpClientFactory log integer status codes
- HTTP: Kestrel and IIS BadHttpRequestException types marked obsolete and replaced
- HttpSys: Client certificate renegotiation disabled by default
- IIS: UrlRewrite middleware query strings are preserved
- Kestrel: Configuration changes at run time 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
- Localization: "Pubternal" APIs removed
- Localization: Obsolete constructor removed in request localization middleware
- Localization: ResourceManagerWithCultureStringLocalizer class and WithCulture interface member removed
- Middleware: Database error page marked as obsolete
- Middleware: Exception Handler Middleware throws original exception if handler not found
- MVC: ObjectModelValidator calls a new overload of ValidationVisitor.Validate
- Security: Cookie name encoding removed
- Security: IdentityModel NuGet package versions updated
- SignalR: MessagePack Hub Protocol moved to MessagePack 2.x package
- SignalR: MessagePack Hub Protocol options type changed
- SignalR: UseSignalR and UseConnections methods removed
- Static files: CSV content type changed to standards-compliant
Code Analysis
- CA1416: Platform compatibility
- CA1417: OutAttribute on string parameter for P/Invoke
- CA1831: Use AsSpan instead of Range-based indexers for string
- CA2013: Do not use ReferenceEquals with value types
- CA2014: Do not use stackalloc in loops
- CA2015: Do not define finalizers for types derived from MemoryManager<T>
- CA2200: Rethrow to preserve stack details
- CA2247: Argument to TaskCompletionSource constructor should be TaskCreationOptions value
Core .NET libraries
- Global assembly cache APIs are obsolete
- Remoting APIs are obsolete
- Most code access security APIs are obsolete
- API obsoletions with non-default diagnostic IDs
- FrameworkDescription's value is .NET instead of .NET Core
- Assembly-related API behavior changes for single-file publishing format
- Order of tags in Activity.Tags is reversed
- Thread.Abort is obsolete
- Obsolete properties on ConsoleLoggerOptions
- Hardware intrinsic IsSupported checks may differ for nested types
- Parameter names changed in reference assemblies
- URI paths with non-ASCII characters parse correctly on Unix
- Uri recognition of UNC paths on Unix
- Environment.OSVersion returns the correct operating system version
- Complexity of LINQ OrderBy.First{OrDefault} increased
- IntPtr and UIntPtr implement IFormattable
- PrincipalPermissionAttribute is obsolete as error
- BinaryFormatter serialization methods are obsolete and prohibited in ASP.NET apps
- UTF-7 code paths are obsolete
- Vector<T> always throws NotSupportedException for unsupported types
- Default ActivityIdFormat is W3C
- Behavior change for Vector2.Lerp and Vector4.Lerp
- SSE and SSE2 CompareGreaterThan methods properly handle NaN inputs
- CounterSet.CreateCounterSetInstance now throws InvalidOperationException if instance already exist
- Microsoft.DotNet.PlatformAbstractions package removed
Cryptography
- Default FeedbackSize value for instances created by TripleDES.Create changed
- Instantiating default implementations of cryptographic abstractions is not supported
- Default TLS cipher suites for .NET on Linux
- System.Security.Cryptography APIs not supported on Blazor WebAssembly
- System.Security.Cryptography.Oid is functionally init-only
Globalization
- Unicode category changed for some Latin-1 characters
- StringInfo and TextElementEnumerator are now UAX29-compliant
- Globalization APIs use ICU libraries on Windows
Interop
- Casting RCW to an
InterfaceIsIInspectable
interface throws PlatformNotSupportedException - No A/W suffix probing on non-Windows platforms
- Built-in support for WinRT is removed from .NET
MSBuild
- TargetFramework change from netcoreapp to net
- PublishDepsFilePath behavior change
- Directory.Packages.props files is imported by default
Networking
- NegotiateStream and SslStream allow successive Begin operations
- Socket.LocalEndPoint is updated after calling SendToAsync
- WinHttpHandler removed from .NET runtime
- MulticastOption.Group doesn't accept a null value
- Cookie Path handling now conforms to RFC 6265
Serialization
- ASP.NET Core apps allow deserializing quoted numbers
- PropertyNamingPolicy, PropertyNameCaseInsensitive, and Encoder options are honored when serializing and deserializing key-value pairs
- Non-public, parameterless constructors not used for deserialization
- JsonSerializer.Serialize throws ArgumentNullException when type parameter is null
- JsonSerializer.Deserialize requires single-character string
- BinaryFormatter.Deserialize rewraps some exceptions in SerializationException
Windows Forms
- TextFormatFlags.ModifyString is obsolete
- DataGridView no longer resets fonts for customized cell styles
- OutputType set to WinExe for WPF and WinForms apps
- DataGridView-related APIs now throw InvalidOperationException
- WinForms and WPF apps use Microsoft.NET.Sdk
- Removed status bar controls
- WinForms methods now throw ArgumentException
- WinForms methods now throw ArgumentNullException
- WinForms properties now throw ArgumentOutOfRangeException
Windows Presentation Framework (WPF)
Also
For more details, you can take a look at the official documentation
Additionnal breaking changes regarding C# 9.0