The DeclarePublicAPIAnalyzer analyzer is a popular third-party analyzer developed at the (https://github.com/dotnet/roslyn-analyzers) repo and published as a NuGet package at https://www.nuget.org/packages/Roslyn.Diagnostics.Analyzers. This analyzer helps track the public surface area of a project with additional readable and reviewable text files that live along with the project sources and provide API documentation as a source. For example, consider the following source file with public and non-public symbols:
public class Class1
{
public int Field1;
public object Property1 => null;
public void Method1() { }
public void Method1(int x) { }
private void Method2() { }
}
The additional API surface text file for this type will look as follows:
Class1
Class1.Class1() -> void
Class1.Field1 -> int
Class1.Method1() -> void
Class1.Method1(int x) -> void
Class1.Property1.get -> object
There is an entry for every public symbol: type Class1, its constructor and it's members Field1, Method1 overloads, and the Property1 getter. Entries contain the entire symbol signature, including the return type and parameters.
With this NuGet package, users can track the shipped and unshipped public API surface at any point of time, get live and build breaking diagnostics when the public API surface is changed, and apply code fixes to update these additional files to match the local API changes. This enables richer and more focused API reviews when the actual code changes are large and spread across the code base, but the API changes can be reviewed by just looking at core signature changes in a single file.
In this section, we will show you how to install and configure the public API analyzer for a C# project, walk you through the additional text files tracking the public API surface, show you the diagnostics reported from this analyzer with API changes, and finally show you how to apply code fixes to fix one or multiple instances of these diagnostics to update the API surface text files.