A built-in tool for checking backward compatibility of NuGet packages

[kunga]

It is hard to always care about backward compatibility when you develop NuGet packages, and easy to break it.

For example, you may just add some optional parameter to a constructor or method.

If you initially had a package MyPackage1 with version 1.0.1:

// version = 1.0.1
namespace MyPackage1;

public class MyClass1
{
    public MyClass1()
    {
    }
}

and then you decided to add some optional parameter to its constructor and forgot (or didn't want) to bump the major version, so that your package MyPackage1 with version 1.0.2 looks like:

// version = 1.0.2
namespace MyPackage1;

public class MyClass1
{
    public MyClass1(bool optionalParam = false)
    {
    }
}

You code will successfully compile and work if it directly uses MyPackage1, but fail in runtime if there is some other package that was compiled with dependency of MyPackage1 with version 1.0.1:

// version = 1.0.1
using MyPackage1;

namespace MyPackage2;

public class MyClass2
{
    public MyClass2()
    {
        var _ = new MyClass1();
    }
}

Because you broke backward compatibility you get an error:

Unhandled exception. System.MissingMethodException: Method not found: 'Void MyPackage1.MyClass1..ctor()'.
   at MyPackage2.MyClass2..ctor()
   at Program.<Main>$(String[] args) in C:\Users\user\RiderProjects\MyPackage\ConsoleApp1\Program.cs:line 3

I don't know a tool or a way to prevent runtime errors because of that. Especially, if you have more than a hundred NuGet dependencies that use each other transitively.

So I wonder if there exists a tool to automatically check backward compatibility during compile time (via analysis of all Nuget dependencies), or during the publishing of a new package to NuGet (when you don't bump the major version)?
And if it doesn’t, are you going to provide it?

I see there is a third-party project (tunnelvisionlabs/dotnet-compatibility) that does similar things, but I’m not sure about its quality, and I suppose that this functionality should be a part of .NET.

[PathogenDavid]

I've never used it myself, but my understanding is Microsoft.CodeAnalysis.PublicApiAnalyzers is a common solution for this.

(You might find this script in the Roslyn repo to be helpful for updating PublicAPI.Shipped.txt.)

---

If you prefer comparing built assemblies, check out Microsoft.DotNet.AsmDiff, which is what the runtime team uses to generate API diffs (See RunApiDiff.ps1 for their specific usage.)

[kunga]

Thanks, it's not ideal and requires lots of CI process improvements, but works.

And backward compatibility should be verified manually using these tools each time.