Glossary / API compatibility

API compatibility

API compatibility describes whether existing consumers continue to compile and behave correctly when a library or runtime is updated. In .NET, compatibility includes source, binary, behavioral, and serialization compatibility across public types, members, attributes, generic constraints, nullability contracts, package assets, and target frameworks.

Compatibility dimensions

Source compatibility asks whether consumer source still compiles. Binary compatibility asks whether previously compiled assemblies can load and call the new library without recompilation. Behavioral compatibility asks whether observable behavior remains acceptable. Removing or renaming public members, changing signatures, adding ambiguous overloads, altering virtual behavior, tightening generic constraints, or changing enum numeric values can be breaking. Nullable annotation changes can introduce warnings or errors for consumers even when CLR signatures remain the same.

Package and runtime compatibility include TFM assets, dependency ranges, assembly binding identity, source generators/analyzers, and native assets. A package can compile on one target but fail on another. Semantic versioning is a promise layered over these technical dimensions, not an automatic guarantee.

Tools and process

Use API compatibility analyzers/baselines and compare public API surfaces in CI. Test a consumer built against an older package, multi-target TFMs, and inspect runtime behavior for key workflows. Maintain an API review process and deprecation path; additive API can still be source-breaking if it creates overload ambiguity or changes resolution.

Interview questions

  1. Source vs binary compatibility? Source checks recompilation; binary checks old compiled clients against new assemblies.
  2. Can adding a method break source compatibility? Yes, overload resolution may become ambiguous or bind differently.
  3. Can nullable annotations be breaking? They can introduce consumer warnings/errors and alter perceived contracts.
  4. What is behavioral compatibility? Existing callers observe acceptable behavior under old assumptions.
  5. How automate checks? Public API baselines/analyzers, package consumer fixtures, and multi-target CI.

References