csharp-sdk/.github/skills/prepare-release/references/apicompat-apidiff.md

API Compatibility and Diff Guide

This reference describes how to run API compatibility checks and generate API diff reports for the C# MCP SDK release process.

API Compatibility Check (ApiCompat)

The SDK uses NuGet's Package Validation to verify API compatibility between releases. This is configured in src/Directory.Build.props:

<EnablePackageValidation>true</EnablePackageValidation>
<PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>

Running ApiCompat

1. Pack the SDK packages to trigger validation:

   dotnet pack src/ModelContextProtocol.Core/ModelContextProtocol.Core.csproj
   dotnet pack src/ModelContextProtocol/ModelContextProtocol.csproj
   dotnet pack src/ModelContextProtocol.AspNetCore/ModelContextProtocol.AspNetCore.csproj
   

   Or pack all at once:

   dotnet pack
   

2. Capture the output. Package validation compares the current public API against the baseline version downloaded from NuGet. Any compatibility issues appear as build warnings or errors.

3. Interpret results:

   • No issues: The API is backward-compatible with the baseline. This is the expected result for PATCH and MINOR releases.
   • Compatibility errors: The API has breaking changes relative to the baseline. These should align with the breaking change audit from Step 3 of the prepare-release skill.
   • Suppressions needed: If intentional breaking changes are confirmed, add entries to CompatibilitySuppressions.xml in the affected project directory.

Updating the Baseline Version

• MAJOR version bump: Update <PackageValidationBaselineVersion> to the previous release version so that ApiCompat validates against the last stable release of the prior MAJOR version. After the new MAJOR release is published, the baseline stays at the new version for future comparisons.
• MINOR or PATCH version bump: Keep <PackageValidationBaselineVersion> at the last MAJOR release version (e.g., keep 1.0.0 when releasing 1.1.0 or 1.0.1).

Compatibility Suppressions

When intentional breaking changes are confirmed, create or update CompatibilitySuppressions.xml in the affected project directory. The repo already uses this pattern — see src/ModelContextProtocol.Core/CompatibilitySuppressions.xml for examples.

<?xml version="1.0" encoding="utf-8"?>
<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:ModelContextProtocol.SomeType.SomeMethod(System.String)</Target>
    <Left>lib/net10.0/ModelContextProtocol.Core.dll</Left>
    <Right>lib/net10.0/ModelContextProtocol.Core.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
</Suppressions>

The exact suppression entries are generated by the pack command when it reports errors — copy the suggested suppression XML from the build output. Remember that suppressions are needed per target framework (net10.0, net9.0, net8.0, netstandard2.0).

Common Diagnostic IDs

ID	Meaning
CP0001	Type or member exists in left but not in right (removed)
CP0002	Member signature changed
CP0005	Virtual member removed from unsealed type
CP0006	Parameter or return type changed
CP0008	Sealed type was previously unsealed

See the full diagnostic list for details.

API Diff Report (ApiDiff)

The API diff report provides a human-readable summary of public API changes between the previous release and the new version. This is included in the release PR description alongside the ApiCompat results.

Important: If the ApiDiff tool cannot be installed or fails to produce output, the release preparation process must pause. Do not fall back to a manual summary. Instead, present the error to the user and ask how to proceed. The user may choose to troubleshoot the tool, skip the API diff section, or abort the release preparation.

Installing Microsoft.DotNet.ApiDiff.Tool

The Microsoft.DotNet.ApiDiff.Tool is published on the .NET transport feed, not on NuGet.org. The transport feed URL follows the pattern https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet{MAJOR}-transport/nuget/v3/index.json, where {MAJOR} is the major version of the .NET SDK from global.json.

1. Determine the SDK major version from global.json:

   # Read the SDK version — e.g. "10.0.100" → MAJOR is 10
   cat global.json
   

2. Install the tool globally with the --prerelease flag (required since the tool is only published as prerelease):

   dotnet tool install --global Microsoft.DotNet.ApiDiff.Tool \
     --prerelease \
     --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet{MAJOR}-transport/nuget/v3/index.json
   

   For example, with .NET SDK 10.x:

   dotnet tool install --global Microsoft.DotNet.ApiDiff.Tool \
     --prerelease \
     --add-source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet10-transport/nuget/v3/index.json
   

3. Verify installation:

   dotnet apidiff --help
   

If the tool is already installed, update it with dotnet tool update using the same flags.

Reference: The dotnet/core repo's RunApiDiff.md documents this same tool and transport feed approach for generating API diff reports between .NET releases.

Generating the API Diff

1. Build the current version in Release configuration:

   dotnet build -c Release
   

2. Download the baseline packages from NuGet:

   mkdir api-diff-temp && cd api-diff-temp
   dotnet new console
   dotnet add package ModelContextProtocol.Core --version {baseline-version}
   dotnet add package ModelContextProtocol --version {baseline-version}
   dotnet add package ModelContextProtocol.AspNetCore --version {baseline-version}
   dotnet restore
   

3. Run the diff for each package, comparing the baseline assembly against the current build. Use dotnet apidiff with -l (left/baseline) and -r (right/current):

   # ModelContextProtocol.Core
   dotnet apidiff \
     -l ~/.nuget/packages/modelcontextprotocol.core/{baseline-version}/lib/net10.0/ModelContextProtocol.Core.dll \
     -r ../artifacts/bin/ModelContextProtocol.Core/Release/net10.0/ModelContextProtocol.Core.dll
   
   # ModelContextProtocol
   dotnet apidiff \
     -l ~/.nuget/packages/modelcontextprotocol/{baseline-version}/lib/net10.0/ModelContextProtocol.dll \
     -r ../artifacts/bin/ModelContextProtocol/Release/net10.0/ModelContextProtocol.dll
   
   # ModelContextProtocol.AspNetCore
   dotnet apidiff \
     -l ~/.nuget/packages/modelcontextprotocol.aspnetcore/{baseline-version}/lib/net10.0/ModelContextProtocol.AspNetCore.dll \
     -r ../artifacts/bin/ModelContextProtocol.AspNetCore/Release/net10.0/ModelContextProtocol.AspNetCore.dll
   

   Note: The exact CLI flags may vary by version. Run dotnet apidiff --help to confirm the available options. If the tool uses different argument names (e.g., --left/--right, --before/--after, or positional arguments), adapt accordingly.

4. Capture the output for each package and format as markdown fenced code blocks with diff syntax highlighting.

5. Repeat for other target frameworks if a more comprehensive report is desired (e.g., net9.0, net8.0, netstandard2.0). At minimum, diff the highest TFM (net10.0).

Per-Package Reports

Generate separate reports for each SDK package:

• ModelContextProtocol.Core — the core library with minimal dependencies
• ModelContextProtocol — the main package with hosting and DI extensions
• ModelContextProtocol.AspNetCore — HTTP-based server implementations

Cleanup

After generating the reports, delete any temporary files (downloaded baseline packages, generated API files, temp projects). These must not be committed.

Presenting Results

In the PR Description

Include both reports in the PR description under dedicated sections:

---

## API Compatibility Report

✅ All packages pass API compatibility validation against v{baseline-version}.

_or_

⚠️ API compatibility issues detected (suppressions added for intentional breaks):

[Detailed ApiCompat output]

## API Diff Report

### ModelContextProtocol.Core

[Diff or table of changes]

### ModelContextProtocol

[Diff or table of changes]

### ModelContextProtocol.AspNetCore

[Diff or table of changes]

In the User Summary (Step 11)

Present a condensed version for the user review:

• ApiCompat: pass/fail with count of issues and suppressions per package
• ApiDiff: count of additions, removals, and changes per package

API Compatibility: ✅ All 3 packages pass (2 existing suppressions in Core)
API Diff: +12 additions, -2 removals, ~3 changes across all packages