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 !

Using ASP.Net Webform Dependency Injection with .NET 4.7.2

Standard

ASP.Net logoStarting with .NET 4.7.2 (released April, 30st), Microsoft offers an endpoint to plug our favorite dependency injection container when developing ASP.Net Webforms applications, making possible to inject dependencies into UserControls, Pages and MasterPages.
In this article we are going to see how to build an adaptation layer to plug Autofac or the container used in ASP.Net Core.
Continue reading

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

Securing the connection between Consul and ASP.Net Core

Standard

The previous article introduced how to use Consul to store configuration of ASP.Net Core (or .Net also). However, it was missing an important thing : the security ! In this article, we will see how we can address this by using ACLs mechanism built into Consul with the previously developed code in order to secure the connection between Consul and ASP.Net Core.
Continue reading

Using Consul for storing the configuration in ASP.Net Core

Standard

Consul logoConsul from Hashicorp is a tool used in distributed architectures to allow service discovery, health checking and kv storage for configuration. This article details how to use Consul for storing the configuration in ASP.Net Core by implementing a ConfigurationProvider.
Continue reading