Detecting breaking changes between two versions of a NuGet package at packaging time
- Gérald Barré
I've already talked about preventing breaking changes in the post I fixed a bug. What should I do now?. But technics evolves, 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> </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>
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 .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>
Do you have a question or a suggestion about this post? Contact me!