A while ago, I wrote about ensuring the correctness of your api and introduced tests to check that you don’t break the contracts. Hopefully, Microsoft introduced a Roslyn analyzer to fulfill this duty in a better manner and help you prevent breaking changes to your APIs. Here’s how !
Set-up the analyzer
The analyzer is contained in a NuGet package that you can install on your .Net Framework and .Net Core projects. Its name is Microsoft.CodeAnalysis.PublicApiAnalyzers (version 2.9.4 at the time of writing).
Installing should be quite usual. Once the analyzer installed, you can start to configure it.
In order to work, you need to add two files in the projects you want to analyze : PublicApi.Shipped.txt and PublicApi.Unshipped.txt to the solution.
In order for the analyzer to take them in account, you have to declare those two files as “Additional Files” in your csproj (having them as Content doesn’t work) :
<AdditionalFiles Include="PublicAPI.Shipped.txt" />
<AdditionalFiles Include="PublicAPI.Unshipped.txt" />
With those two files set, you will see that all your public members/classes will have squiggles suggesting that they’re not part of the API and therefore you should add them.
Hopefully, the light bulb is here to help. You click on it to fix this and add all the public members to those two files.
Shipped, unshipped
By default, all added members by the Roslyn fix will be written in the PublicApi.Unshipped.txt file.
It’s up to you on how you manage the content of those two files according to your release/branching strategy.
However, here are few tips I could advise.
If you’re working with a Git flow branching strategy, all the changes should go into the unshipped file. When making the PR, reviewers have to check two things : shipped file didn’t change, unshipped file changes don’t break the compatibility (unless wanted).
Once merged and integrated into develop branch, all the changes are going to stack in the file.
When preparing a release (and therefore creating the branch to) you can move all the lines to the shipped file as you’re shipping those members in the API.
If working with GitHub flow, same should be done before merging the PR to master.
Break all the things !
Ok, now you’re able to track all the changes to your API. However, when making a change to it, you’ll see only warnings in Visual Studio (or your build pipeline).
If you want to go further (and I suggest you do), you can treat several warnings as errors in your csproj :
<WarningsAsErrors>$(WarningsAsErrors);RS0016;RS0017;RS0022;RS0024;RS0025;RS0026;RS0027</WarningsAsErrors>
You can look for more information about the rules on GitHub.
Now, you’re ready to ship well your APIs !