Breaking changes in .NET 9

If you're migrating an app to .NET 9, 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.


This article is a work in progress. It's not a complete list of breaking changes in .NET 9. To query breaking changes that are still pending publication, see Issues of .NET.


Title Type of change Introduced version
DefaultKeyResolution.ShouldGenerateNewKey has altered meaning Behavioral change Preview 3

Core .NET libraries

Title Type of change Introduced version
Adding a ZipArchiveEntry with CompressionLevel sets ZIP central directory header general-purpose bit flags Behavioral change Preview 5
API obsoletions with custom diagnostic IDs Source incompatible Preview 1
Creating type of array of System.Void not allowed Behavioral change Preview 1
Default Equals() and GetHashCode() throw for types marked with InlineArrayAttribute Behavioral change Preview 6
Inline array struct size limit is enforced Behavioral change Preview 1
InMemoryDirectoryInfo prepends rootDir to files Behavioral change Preview 1
RuntimeHelpers.GetSubArray returns different type Behavioral change Preview 1
Support for empty environment variables Behavioral change Preview 6


Title Type of change Introduced version
HttpListenerRequest.UserAgent is nullable Source incompatible Preview 1

SDK and MSBuild

Title Type of change Introduced version
dotnet workload commands output change Behavioral change Preview 1
installer repo version no longer documented Behavioral change Preview 5
Terminal logger is default Behavioral change Preview 1
Warning emitted for .NET Standard 1.x Source incompatible Preview 6

Windows Forms

Title Type of change Introduced version
BindingSource.SortDescriptions doesn't return null Behavioral change Preview 1
Changes to nullability annotations Source incompatible Preview 1
ComponentDesigner.Initialize throws ArgumentNullException Behavioral change Preview 1
DataGridViewRowAccessibleObject.Name starting row index Behavioral change Preview 1
No exception if DataGridView is null Behavioral change Preview 1
PictureBox raises HttpClient exceptions Behavioral change Preview 6


Title Type of change Introduced version
GetXmlNamespaceMaps type change Behavioral change/Source incompatible Preview 3

See also