24

I'm working on a C# 3.5 assembly that is consumed by many different applications in an enterprise server environment. I would like to add some properties to an existing C# class (not abstract) and maintain backwards compatibility with current clients without recompiling. It’s a strongly named 3.5 assembly. Existing client applications will not be recompiled. Instead we use publisher policy assemblies to re-direct existing clients to the updated version.

What are the rules for maintaining this type of class backward compatibility?

I'm looking for some set of rules I can validate my code changes against.

After my current attempts at updating the class clients are throwing a "The located assembly's manifest definition does not match the assembly reference" exception.

ErnieL
  • 5,685
  • 20
  • 27
  • 3
    See [A definite guide to API-breaking changes in .NET](http://stackoverflow.com/questions/1456785/a-definite-guide-to-api-breaking-changes-in-net) – Justin Mar 16 '11 at 02:25
  • @Kragen - Thanks! Best reference I've seen yet. If you make your comment an answer I'll accept it. – ErnieL Mar 16 '11 at 15:44

3 Answers3

3

The best reference is Justin's answer: A definite guide to API-breaking changes in .NET

@Justin - if you ever post this as an answer, I'll give you the check.

Community
  • 1
  • 1
ErnieL
  • 5,685
  • 20
  • 27
2

You have to maintain the same assembly version (i.e. don't increment it across builds) — see the AssemblyVersionAttribute in MSDN.

Also, you could leverage assembly binding redirects, but that involves config file changes which I don't expect to be desirable in your case.

Ondrej Tucny
  • 26,009
  • 6
  • 63
  • 87
  • We have publisher policy assemblies that handle version number changes: http://msdn.microsoft.com/en-us/library/7wd6ex19.aspx. That’s not the issue. – ErnieL Feb 22 '11 at 23:14
2

At his point error that you are getting is not related to compatibility between classes, but rather problem loading assembly - see The located assembly's manifest definition does not match the assembly reference if it helps.

Adding properties/methods to exisitng class should be ok for backward compatibility. Removing fields/methods/properties, changing class to struct, changing base class is definitely not. Modifying constants, enum values is dangerous.

Community
  • 1
  • 1
Alexei Levenkov
  • 94,391
  • 12
  • 114
  • 159
  • What you are saying aligns with my understanding. However I still managed to break something… Do you know anywhere this is officially documented? My attempts at google and MSDN searches have failed. – ErnieL Feb 22 '11 at 23:03
  • I don't know if there is a good overview on MSDN. I do recommend reading "Framework Design Guidelines" book if you have time as it covers all sorts of issues with designing class hierarchies. You can also read blogs like http://blogs.msdn.com/b/bclteam/archive/2004/09/07/226489.aspx and http://blogs.msdn.com/b/kcwalina/archive/tags/design+guidelines/default.aspx – Alexei Levenkov Feb 23 '11 at 01:16
  • 1
    Changing a field to a property is a NO-NO-NO (clearly the opposite, property to field is a NO-NO-NO). Adding an IDisposable interface is a breaking change from the POV of the user, but probably it won't directly break the running of the thing (simply resources won't be freed timely) – xanatos Feb 24 '11 at 06:59
  • Thanks xanatos for explicitly calling out field to property change is breaking change (it was implied in my answer as it requires remoing field or property), but it is better to be explicit in this case. – Alexei Levenkov Feb 24 '11 at 18:59