Breaking changes and the BCL [Ari Weinstein]

  • Article

               One of the areas that I have been involved in for the past half year is application compatibility.  Since then I have a number of emails from our .NET 2.0 compatibility alias (netfxcmp@microsoft.com-let us know if you have any compat questions!) with reports of compatibility issues when migrating applications from .NET 1.1 to .NET 2.0.  I wanted to take this opportunity to point you to a few useful documents which discuss our policy on application compatibility, known breaking changes from v1.1 to v2.0, as well as functionality which you may expect us to change from version to version.    

The Breaking Changes in a Managed World package contains quite a few goodies, made up of many source code samples as well as a lengthy (about 50 page) document which lays out the policy on compatibility throughout the framework.  This document explains exactly what our stance on compat is, reading through it you can see exactly what our justification for allowing certain classes of changes to be made from version to version, as well as what classes of changes we try our hardest to prevent. 

Another link which should be highly useful to anyone who is wondering policy aside, what breaking changes have actually been made between v1.1 and v2.0, look no further than Breaking Changes in .NET Framework 2.0 on MSDN.  The list of breaking changes there is broken down by design-time (what changes will cause breaks when you migrate source code, for example) versus run-time (breaks which occur when running the application in the newest version of the runtime) breaking changes.

            As I mentioned previously, there are some aspects of the BCL that you should expect us to change, or to put it more accurately, there is some functionality that should not surprise you if changed.  At a high level, this information is contained in the document in the package linked to above, but I wanted to give some concrete examples of where some have relied on functionality they shouldn’t have and ran into issues migrating from v1.1 to v2.0:

  • The actual value of hashcodes for objects in the framework, if you need to use hashes try those in the System.Security.Cryptography namespace.
  • The values generated by the random number generator based on a constant seed value.
  • The exact accuracy of float/double arithmetic.  We may, and have, increased the accuracy of these operations which leads to slight differences in results when working with some values.
  • Ordering in private reflection – this is almost guaranteed to change.

Of course, we never go out of our way explicitly to break existing code, any time that we make changes even to areas where we specifically state we may change the behavior, the break must be reviewed an justified – there are just some instances where it is easier to justify the change because we state upfront that this behavior may vary from version to version. 

            Hopefully the documents and pages listed above will help provide guidance as to what expectations you can have for changes in behavior in future versions of the framework.  We can’t make guarantees about maintaining compatibility in all situations, but we go out of our way to make migration as simple as possible, and only make changes when there are compelling reasons to do so.  Definitely respond to this blog entry or email the compat alias netfxcmp if you have any questions.

   -Ari