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

I've already talked about preventing breaking changes in the post I fixed a bug. What should I do now?. But things evolve, and now the .NET SDK provides new features to help NuGet package authors to detect breaking changes between two versions of a NuGet package when building a new version.

Starting with .NET 6, the .NET SDK provides a new feature called Package Validation that allows NuGet package authors to validate multiple aspects of their packages. This feature is not enabled by default, so you must opt-in by adding the following property 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 version of the package that will be used as a baseline for the validation. This version must be available on a NuGet feed. If you want to use a different location or if the baseline package is not accessible on NuGet, you can 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 will report errors after building the package. For instance, if you add the sealed modifier to a class, the .NET SDK will report an error:

You can generate a suppression file if a breaking change is expected:

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

Last but not least, you can 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!