Not So Stupid Question 330: What's the Difference Between Binary and Source Compatibility?

When .NET 7 was released to the general public there were unavoidable breaking changes. It’s unfortunate, but you can’t have great things without breaking something. To make the jump from .NET 6 to 7 a little bit easier, Microsoft made Compatibility Issues clearer by differentiating between Binary Compatibility and Source Compatibility. This isn’t something new. What is new is making this a part of the documentation.

Binary compatibility This means the already compiled application (the ready-to-use version) will work with the new .NET version without any issues. You don’t have to do anything to make it work; it just runs as it did before. Just drop in the binary and you are good to go.

Source compatibility This means you can compile your application’s source code (the code you wrote) using the new .NET version without needing to make any changes. You don’t have to edit your code to make it work with the new version. You need to rebuild using the specific version.

To summarize, binary compatibility is about your compiled application working with the new .NET version, while source compatibility is about your source code being able to compile with the new .NET version without changes. Source compatibility does not imply binary compatibility.

In addition, for every breaking change, Microsoft documented the reason behind the change as well as the new behavior by using the following layout:

• About
• Version introduced
• Previous behavior
• New behavior
• Type of breaking change (source, binary or both)
• Reason for change
• Recommended action

{{ template “_internal/disqus.html” . }}

Last modified on 2024-03-15