dotnet-library-api-compat

To maintain .NET library compatibility, you must distinguish between safe and breaking API changes at both binary and source levels, ensuring consumers can update without compilation errors or runtime exceptions like TypeLoadException.

You can move types between assemblies without breaking .NET library consumers by using type forwarders, which redirect the runtime to the new assembly location and prevent TypeLoadException during assembly reorganization.

API changes map to Semantic Versioning increments by assigning major version bumps for breaking changes, minor bumps for new backward-compatible functionality, and patch bumps for backward-compatible bug fixes in .NET libraries.

Adding a new public method to a non-sealed class can affect binary compatibility in .NET if derived classes exist, as it changes the virtual method table layout and may cause runtime binding failures in un-recompiled consumers.

The best way to manage API deprecation in .NET 8.0 SDK-style projects is by applying the [Obsolete] attribute, which allows you to communicate upcoming breaking changes and map the lifecycle to Semantic Versioning increments.

You need type forwarders when refactoring core types into a new .NET assembly to ensure existing users do not encounter TypeLoadException, maintaining binary compatibility without forcing consumers to recompile against the new structure.