This document contains information regarding API baseline files and how to work with them.
Each project contains two files tracking the public API surface of said project. These files are used by the Microsoft.CodeAnalysis.PublicApiAnalyzers roslyn analyzer as a reference to what the public API surface looked like previously.
This file contains APIs that were released in the last major version.
This file should only be modified after a major release by the maintainers and should never be modified otherwise. There is a script to perform this automatically.
This file contains API changes since the last major version.
There are three types of public API changes that need to be documented.
This case will be indicated by an error/warning like the following:
RS0016: Symbol 'X' is not part of the declared API
It can be resolved by adding the new symbol to the PublicAPI.Unshipped.txt file:
#nullable enable
Microsoft.AspNetCore.Builder.NewApplicationBuilder.New() -> Microsoft.AspNetCore.Builder.IApplicationBuilder!
This change can be performed automatically by your IDE or using a script.
Note: Be sure to apply the Code-Fix on a solution level, if there are many new APIs that need to be documented.
This case will be indicated by an error/warning like the following:
RS0017: Symbol 'X' is part of the declared API, but is either not public or could not be found
It can be resolved by adding the removed symbol to the PublicAPI.Unshipped.txt file:
#nullable enable
*REMOVED*Microsoft.Builder.OldApplicationBuilder.New() -> Microsoft.AspNetCore.Builder.IApplicationBuilder!
This change needs to be done manually. Copy the relevant line from PublicAPI.Shipped.txt into PublicAPI.Unshipped.txt and place *REMOVED* in front of it.
Two new entries need to be added to the PublicAPI.Unshipped.txt file for an updated API. One to remove the old API and one for the new API. For example:
#nullable enable
*REMOVED*Microsoft.AspNetCore.DataProtection.Infrastructure.IApplicationDiscriminator.Discriminator.get -> string!
Microsoft.AspNetCore.DataProtection.Infrastructure.IApplicationDiscriminator.Discriminator.get -> string?
The removed case needs to be done manually as explained here.
Projects ending in .Tests or .Resources are ignored per default.
If you need to manually ignore a project, include the following in its .csproj file:
<PropertyGroup>
<AddPublicApiAnalyzers>false</AddPublicApiAnalyzers>
</PropertyGroup>The two text files mentioned above need to be added to each new project.
There is a template file called PublicAPI.empty.txt in the src directory that can be copied over into a new project.
DIR="<new-project-folder>"
cp "src/PublicAPI.empty.txt" "src/$DIR/PublicAPI.Shipped.txt"
cp "src/PublicAPI.empty.txt" "src/$DIR/PublicAPI.Unshipped.txt"A PR to main will trigger a Pipeline job that runs the CheckPublicApi script.
The job is defined as part of this Pipeline definition.
There are some helpful scripts that accommodate working with the analyzer.
The scripts can be executed via Nuke. Choose the appropriate build script for your platform (in the root directory) and pass one of the following arguments.
Executes a build and fails if there are undocumented changes.
./build.sh CheckPublicApiThis will use the dotnet-format tool to fix all the RS0016 warnings of the Microsoft.CodeAnalysis.PublicApiAnalyzers.
./build.sh AddUnshippedApiThis shows all changes of PublicAPI.Shipped.txt files between git refs. Tags, commit hashes and branch names are supported.
./build.sh DiffShippedApi --from 11.0.0 --to 12.0.0This will output the contents of all PublicAPI.Unshipped.txt files throughout the project.
./build.sh DisplayUnshippedApiIf we only want to see the breaking changes, we can add the breaking flag:
./build.sh DisplayUnshippedApi --breakingThis transfers all changes in the PublicAPI.Unshipped.txt to the PublicAPI.Shipped.txt files.
It also takes care of removing lines marked with *REMOVE* (removals of APIs).
./build.sh MarkApiShipped