Breaking Changes and Managed Code: From Theory to Reality

1
Breaking Changes and Managed Code From Theory to
Reality

• Kit George
• Program Manager
• Base Class Libraries Team, CLR
• kitg_at_microsoft.com

2
Agenda

• Compatibility The Concept
• The Problem
• Rule-Of-Thumb Priorities
• The .NET Process
• Definitions
• The Theory Breaking Changes
• Being Up-Front
• The Theory Non-Breaking Changes
• The Reality
• Resources

3
Compatibility The Concept

• The ability to run a client built to run on an
  existing service, against a newer version of that
  service

• Example
• Service Win98 to Win2000
• Client Office98, ChessMaster, Master Of Magic,
  PaintShopPro

Key Term Preserving Your Investment
4
The Problem

• Compatibility constrains
• The ability to innovate
• The ability to fix

• Finding The Sweet Spot
• There are very few absolutes for breaking changes
• Having real applications helps determine the
  breakingness of a given change

The world is gray, Jack (Clear and Present
Danger)
5
Rule-of-Thumb Priorities

• Security overrides compatibility
• Generally enforced (turn off is not an option)
• Reliability/Compatibility are contentious
• If the issue is close, the ability to turn off
  may be provided
• Conceptually odd typically means turning
  reliable behavior into unreliable behavior
• Everything else comes last
• Performance, Ease-Of-Use, Correctness

6
The Process

• We have a guideline for breaking changes
• Includes descriptions of allowed/disallowed
  changes
• http//msdn.microsoft.com/netframework/programming
  /bcl/
• Use libcheck to identify most severe changes
  (link above)
• We have a review body, that reviews all known
  breaking changes
• We have the appcompat lab
• Any discovery of an actual break in an
  application, immediately raises questions for the
  change

On a case by case basis, the decisions are right
Problem Death by a thousand papercuts
7
Definitions Binary Compat.

• If an assemblys public signatures have been
  removed, or altered so that clients could no
  longer access the same interfaces exposed by the
  assembly, the change is said to be a binary
  incompatible change

8
The spot the break game

• V1 Service

class Test public string Description get
set
V2 Service
class Test public string Description set

Client
Console.WriteLine(new Test().Description)
9
The spot the break game

• V1 Service

class Test public static string GetLongest(
string s1, string s2 )
V2 Service
class Test public static string GetLongest(
string s1, params string s2 )
Client
NO BREAK!
10
Definitions Source Compat.

• If a client can still bind to a service if the
  service is changed, but attempting to recompile
  the client would require changes to the code for
  that client in order for it to bind successfully,
  the change in the service is termed a source
  incompatible change

11
The spot the break game

• V1 Service

class Test public static Decimal Floor(
Decimal value )
V2 Service
class Test public static Decimal Floor(
Decimal value ) public static Double
Floor( Double value )
Client
Console.WriteLine(Test.Floor(23))
12
Definitions Behavioral compat.

• Any change which results in a change in behavior
  of a given client, is said to be a behaviorally
  incompatible change

At the end of the day, this description could
encompass all changes. It is however, intended to
describe only changes within a given API
13
The spot the break game

• V1 Service

class Test public static int GetLower( int
i1, int i2 )
V2 Service
class Test public static int GetLower( int
i1, int i2 )
Client
Console.WriteLine(0 lower than 1? 2, i1,
i2, Test.GetLower(i1, i2) i1))
Behavioral Compat Devil is in the details
14
Definitions Backwards compat.

• If a client bound to a previous version of a
  service, is not able to bind to a newer version
  of the service, or no longer behaves in the same
  way when binding to the newer version of the
  service, then the newer service is said to be
  backwards incompatible.

15
The Theory Breaking Changes

• Examples

16
Being Up-Front

• If a particular change is deemed acceptable in
  theory (or even in judgement) but it affects a
  broad set of users, it may not be enacted
• If a particular change is deemed unacceptable in
  theory, it may be judged to be acceptable in
  practice

Every Known Change is assessed
17
The Theory Non-Breaking Changes

• ToString changes are typically allowed
• Error messages are allowed to change
• Mitigation localization of messages
• No longer throwing an exception
• Can be contentious, and may be addressed on a
  case-by-case basis
• Adding members
• Problematic for reflection
• Sometimes not performed when it affects source
  compatibility

18
The Theory Non-Breaking Changes

• Adding FlagsAttribute to an enum
• Of course, this is typically behaviorally
  breaking
• Adding a value to an existing enum
• One of the most contentious issues
• Removing, adding, or modifying private fields
• Most interesting if it affects serialization
• When it affects serialization, may be re-addressed

19
The Theory Non-Breaking Changes

• Increasing the number accuracy of a given
  floating point operation
• Even called out in the CLI standard
• http//dotnet.di.unipi.it/EcmaSpec/PartitionI/con
  t11.html_Toc527182172
• Adding the obsolete attribute
• Make sure its not overdone

20
The Reality Specific BreaksCLR

• Emitting Bad Metadata
• In V1.1, we allowed emitting of clearly broken
  metadata, such as a ref byte type
• Reflection Order of result of GetMembers
• GetMembers on Type returned an ordered list of
  values in V1.1 now Its randomized
  (purposefully)
• ApartmentState
• In V1.1, we accidentally allowed setting of
  ApartmentState on THIS thread once the thread was
  started. This resulted in indeterministic
  behavior
• We have an appconfig switch to give you back the
  indeterminism
• Limited only to whidbey apps running on Whidbey

21
The Reality Specific BreaksWindows.Forms

• CheckedListBox generates KeyPress on space
• In V1.1, CheckedListBox didnt generate a
  keypress event for space
• ListView no longer fires MouseUp on move
• In V1.1, drag-dropping while IN a drag, would
  fire the MouseUp event now it does not
• RadioButton checked on Enter
• In V1.1, entering a radiobutton group would
  result in the first button being checked not so
  in V2.0, they need to hit Enter/Arrows to select
  the first item

22
The Reality Specific BreaksWeb.NET

• Recognition of certain special folder
• In Whidbey, ASP have designated certain
  subfolders as special. Resources, Code, Data,
  and Theme are all recognized in special ways
• Limiting the upload size with maxRequestLength
• Upload size simply didnt work if bigger than 2GB
  previously, but wasnt explicitly disallowed. Now
  it throws a configuration Exception

23
Resources

• The Breaking Change doc (basis for much of this
  talk)
• http//msdn.microsoft.com/netframework/programmin
  g/bcl/
• Brad Abrams post on Obsoletions
• http//blogs.msdn.com/brada/archive/2004/11/22/26
  7950.aspx
• Intra-Whidbey obsoletions doc
• http//www.microsoft.com/downloads/details.aspx?f
  amilyid7a89e36b-e486-4ee3-98b9-173c262a9f31displ
  aylangen
• Breaking Change List
• http//www.gotdotnet.com/team/changeinfo/default.
  aspx
• LibCheck
• http//www.microsoft.com/downloads/details.aspx?f
  amilyid4b5b7f29-1939-4e5b-a780-70e887964165displ
  aylangen