Rules for C# class backward compatibility/avoiding breaking changes

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.


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.


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.