Detecting breaking changes between two versions of a NuGet package at packaging time

I've previously covered preventing breaking changes in I fixed a bug. What should I do now?. The .NET SDK has since added new features to help NuGet package authors detect breaking changes between package versions during the build process.

Starting with .NET 6, the .NET SDK includes a feature called Package Validation that allows NuGet package authors to validate multiple aspects of their packages. This feature is not enabled by default; opt in by adding the following properties to your project file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.0.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>
</Project>

<PackageValidationBaselineVersion> specifies the package version to use as a baseline for validation. This version must be available on a NuGet feed. If the baseline package is not accessible on NuGet or you need to reference a local file, use the <PackageValidationBaselinePath> property instead:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <Version>1.1.0</Version>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
    <PackageValidationBaselinePath>path_to_nupkg\SampleClassLibrary.1.0.0.nupkg</PackageValidationBaselinePath>
  </PropertyGroup>
</Project>

When building the package using dotnet pack, the .NET SDK reports errors if breaking changes are detected. For instance, adding the sealed modifier to a class triggers the following error:

If a breaking change is intentional, you can generate a suppression file:

<PropertyGroup>
  <GenerateCompatibilitySuppressionFile>true</GenerateCompatibilitySuppressionFile>
  <CompatibilitySuppressionFilePath>ApiCompatSuppressions.xml</CompatibilitySuppressionFilePath>
</PropertyGroup>

You can also enable a stricter validation mode by adding the following property to your project file:

<PropertyGroup>
  <EnableStrictModeForBaselineValidation>true</EnableStrictModeForBaselineValidation>
</PropertyGroup>

#Additional resources

• Validate against a baseline package version
• GitHub .NET SDK - ApiCompat

Do you have a question or a suggestion about this post? Contact me!