This is an Azure Pipelines encapsulation of the ApiCompat tool. To get the lastest version of this tool please visit dotnet/arcade repo. We do not own the original tool, we just created this task to have an easy way to use it on Azure Pipelines.
API Compat tool compares two sets of assemblies and determines if the implementation has incompatibilities with the contract.
How to configure it
Contracts root folder
Path to the folder that contains the assemblies to compare against.
Contracts files name
Space separated list of the names of the assemblies to compare to.
Implementation assemblies folder
Folder that contains the assemblies that are going to be compared against the contracts.
Fails on Issue
Checking this will cause the build process to fail when ApiCompat finds one or more incompatibilities. Leaving it unchecked will flag the task as successful with issues. For Pull Requests we recommend to leave this checked to alert to alert the Pull Request user that his implementations caused incompatibilities.
If a contract or implementation dependency cannot be found in the given directories, fallback to try to resolve against the framework directory on the machine.
Warn on incorrect version
Warn if the contract version number doesn't match the found implementation version number.
Warn on missing assemblies
Warn if the contract assembly cannot be found in the implementation directories. Default is to error and not do analysis.
Create Comparison Result Log
If this is checked, a JSON file will be created with the comparison result.
The JSON will contain two properties:
Checking this will also show two additional input boxes:
Use Baseline File
A baseline file is a file that contains known incompatibilities. This come useful whenever one want to release a new major version of the assembly, knowing beforehand that the new version will contain breaking incompatibilities.
The content of this file is simply the same output generated by ApiCompat, either by piping the result to a text file or by using the
When running ApiCompat with this file as optional parameter with
Checking this option will make appear a input field to select a baseline file, and it will be fed as parameter to ApiCompat when running the comparison.
If you have a build process for your assemblies, this tool can be very useful to prevent the integration of new changes that will cause incompatibilities with the current released version of your assemblies.
To do this in your build process, add this task and configure the following fields:
For the build trigger configure Pull request validation.
With this configuration, whenever a person opens a Pull Request introducing changes that will break compatibilities with the current released version, the build process will be marked as Failed.