Proj0250.md

parent	ancestor
Packaging	Rules

Proj0250: Generate API compatibility suppression file

When package validation is enabled, it is required to provide a suppression file for all differences that occur in the API:

• Changes between different package versions
• Differences between different runtimes (e.g. windows vs unix)
• Differences between different target frameworks (e.g. netstandard2.0 vs net8.0)

This suppression file can be created manually, or automatically generated by enabling the GenerateCompatibilitySuppressionFile property. It is advised to enable this property in the project file to ensure that the file is kept up-to-date automatically.

Additionally, it is advised to keep changes to the generated file tracked in your version control system to ensure any API changes are explicitly included in code reviews.

More information can be found here, here and here.

Non-compliant

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <EnablePackageValidation>true</EnablePackageValidation>
    <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
  </PropertyGroup>

</Project>

Or:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <EnablePackageValidation>true</EnablePackageValidation>
  </PropertyGroup>

</Project>

Compliant

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <EnablePackageValidation>true</EnablePackageValidation>
    <ApiCompatGenerateSuppressionFile>true</ApiCompatGenerateSuppressionFile>
  </PropertyGroup>

</Project>