Prevent breaking changes to your APIs with Roslyn

Standard

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.
Roslyn suggest that you should add the members to the API
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 !

Ensuring the correctness of your API

Standard

Designing and maintaining an API is hard. Whether you’re distributing assemblies, creating NuGet packages or exposing services (such as WCF, SOAP or REST), you must pay attention to the contracts you provide. The contract must be well designed for the consumer and must be stable over time. In this article, we’re going to see some rules to follow, tips to help and tools to use to ensure that your APIs are great to use.
Although this post is applied to the .Net environment, most of it can be used with other environments (Java, Node, Python, etc.).
Continue reading