build: add ApiCompat support to handle breaking changes

.gitignore

@@ -417,3 +417,6 @@ FodyWeavers.xsd
 *.msm
 *.msp
 .claude/
+
+# ApiCompat baseline assemblies
+!**/LastMajorVersionBinary/*.dll

README.md

@@ -220,5 +220,22 @@ Pull requests are welcome. For major changes, please open an issue first to disc
 
 Please make sure to update tests as appropriate.
 
+## Breaking Changes
+The generated API surface is validated against a baseline using [ApiCompat](https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/overview). Each `Example.OpenApi*` project has a `LastMajorVersionBinary/` directory containing the baseline reference assembly.
+
+### Introduce Breaking Change
+Build will fail when a breaking change is detected. Generate a suppression file for the breaking changes, and commit it to accept the breaking changes:
+```Shell
+dotnet build -p:ApiCompatGenerateSuppressionFile=true
+```
+
+### Update Baseline
+The baseline doesn't need to be updated when using suppression files, but if it for some reason should, run:
+```Shell
+dotnet build -p:_ApiCompatGenerateContractAssembly=true -p:ApiCompatValidateAssemblies=false
+```
+
+This copies the current reference assemblies to `LastMajorVersionBinary/` for each example project. Commit the updated DLLs. The suppression files should also be purged at this point.
+
 # License
 [MIT](LICENSE)

tests/Directory.Build.props

@@ -0,0 +1,16 @@
+<Project>
+    <PropertyGroup>
+        <_ApiCompatGenerateContractAssembly>false</_ApiCompatGenerateContractAssembly>
+        <_ApiCompatCaptureGroupPattern>.+%5C$([System.IO.Path]::DirectorySeparatorChar)(.+)%5C$([System.IO.Path]::DirectorySeparatorChar)(.+)</_ApiCompatCaptureGroupPattern>
+    </PropertyGroup>
+
+    <Target Name="ApiCompatGenerateContractAssembly" AfterTargets="Build" Condition="'$(_ApiCompatGenerateContractAssembly)' == 'true' And $([System.Text.RegularExpressions.Regex]::IsMatch($(MSBuildProjectName), '^Example\.OpenApi\d+$'))">
+        <Copy SourceFiles="$(IntermediateOutputPath)ref/$(AssemblyName).dll"
+              DestinationFolder="LastMajorVersionBinary" />
+    </Target>
+
+    <ItemGroup>
+        <!-- Generate OS-agnostic Right suppression directives -->
+        <ApiCompatRightAssembliesTransformationPattern Include="$(_ApiCompatCaptureGroupPattern)" ReplacementString="obj/$1/$2" />
+    </ItemGroup>
+</Project>

tests/Example.OpenApi20/Example.OpenApi20.csproj

@@ -5,11 +5,17 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <RootNamespace>Example.OpenApi20</RootNamespace>
+
+        <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
+        <ApiCompatContractAssembly>LastMajorVersionBinary/$(AssemblyName).dll</ApiCompatContractAssembly>
+        <!-- https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids -->
+        <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
     </PropertyGroup>
 
     <ItemGroup>
         <PackageReference Include="Corvus.Json.ExtendedTypes" Version="4.4.2" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.12" />
+        <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="10.0.202" PrivateAssets="all" IsImplicitlyDefined="true" />
         <PackageReference Include="ParameterStyleParsers.OpenAPI" Version="1.4.0" />
     </ItemGroup>
 

tests/Example.OpenApi30/Example.OpenApi30.csproj

@@ -5,10 +5,16 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <RootNamespace>Example.OpenApi30</RootNamespace>
+
+        <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
+        <ApiCompatContractAssembly>LastMajorVersionBinary/$(AssemblyName).dll</ApiCompatContractAssembly>
+        <!-- https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids -->
+        <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
     </PropertyGroup>
 
     <ItemGroup>
         <PackageReference Include="Corvus.Json.ExtendedTypes" Version="4.4.2" />
+        <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="10.0.202" PrivateAssets="all" IsImplicitlyDefined="true" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.12" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="9.0.12" />
         <PackageReference Include="ParameterStyleParsers.OpenAPI" Version="1.4.0" />

tests/Example.OpenApi31/Example.OpenApi31.csproj

@@ -5,10 +5,16 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <RootNamespace>Example.OpenApi31</RootNamespace>
+
+        <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
+        <ApiCompatContractAssembly>LastMajorVersionBinary/$(AssemblyName).dll</ApiCompatContractAssembly>
+        <!-- https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids -->
+        <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
     </PropertyGroup>
 
     <ItemGroup>
         <PackageReference Include="Corvus.Json.ExtendedTypes" Version="4.4.2" />
+        <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="10.0.202" PrivateAssets="all" IsImplicitlyDefined="true" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" Version="9.0.12" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.12" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="9.0.12" />

tests/Example.OpenApi32/Example.OpenApi32.csproj

@@ -5,10 +5,16 @@
         <Nullable>enable</Nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <RootNamespace>Example.OpenApi32</RootNamespace>
+
+        <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
+        <ApiCompatContractAssembly>LastMajorVersionBinary/$(AssemblyName).dll</ApiCompatContractAssembly>
+        <!-- https://learn.microsoft.com/en-us/dotnet/fundamentals/apicompat/diagnostic-ids -->
+        <ApiCompatGenerateSuppressionFile>false</ApiCompatGenerateSuppressionFile>
     </PropertyGroup>
 
     <ItemGroup>
         <PackageReference Include="Corvus.Json.ExtendedTypes" Version="4.4.2" />
+        <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="10.0.202" PrivateAssets="all" IsImplicitlyDefined="true" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.Certificate" Version="9.0.12" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.JwtBearer" Version="9.0.12" />
         <PackageReference Include="Microsoft.AspNetCore.Authentication.OpenIdConnect" Version="9.0.12" />