Breaking changes and the BCL [Ari Weinstein]

               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 ( 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.


Comments (7)
  1. Anonymous says:


    I read your blog with great intrest and appreciate your insights.

    Thank you,


  2. Anonymous says:

    The change detailed at is very annoying (and apparently someone forgot to update the docs, which is very handy).

    We wasted a couple of weeks on that puppy. The fact that all the official docs are still wrong and that it isn’t mentioned at doesn’t inspire confidence…

  3. Makoto says:

    I suspect there are more breaking changes than that the above links say.

    For example, IPAddress.Parse("") returns in .NET 1.x, but throws exception in .NET 2.0.  I trapped this last year…

    (I know my code was wrong.)

    And it’s still not mentioned there.

    Should I report to netfxcmp@…?

  4. BCL Team says:

    Makoto, thanks for this report.  I’ll look into it and try and get the data into the next doc refresh we have.  So in short, no need to email netfxcmp on this particular issue; I’ll make sure the change is logged.


  5. Anonymous says:


    Any reason why the docs have not been updated (see my earlier comment)?



  6. Anonymous says:

    Woohoo! The squeaky wheel gets the grease…

Comments are closed.

Skip to main content