dotnet-api-surface-validation

What this skill does

# dotnet-api-surface-validation

Tools and workflows for validating and tracking the public API surface of .NET libraries. Covers three complementary approaches: **PublicApiAnalyzers** for text-file tracking of shipped/unshipped APIs with Roslyn diagnostics, the **Verify snapshot pattern** for reflection-based API surface snapshot testing, and **ApiCompat CI enforcement** for gating pull requests on API surface changes.

**Version assumptions:** .NET 8.0+ baseline. PublicApiAnalyzers 3.3+ (ships with `Microsoft.CodeAnalysis.Analyzers` or standalone `Microsoft.CodeAnalysis.PublicApiAnalyzers`). ApiCompat tooling included in .NET 8+ SDK.

**Out of scope:** Binary vs source compatibility rules, type forwarders, SemVer impact -- see [skill:dotnet-library-api-compat]. NuGet packaging, `EnablePackageValidation` basics, and suppression file mechanics -- see [skill:dotnet-nuget-authoring] and [skill:dotnet-multi-targeting]. Verify library fundamentals (setup, scrubbing, converters) -- see [skill:dotnet-snapshot-testing]. General Roslyn analyzer configuration (EditorConfig, severity levels) -- see [skill:dotnet-roslyn-analyzers]. HTTP API versioning -- see [skill:dotnet-api-versioning].

Cross-references: [skill:dotnet-library-api-compat] for binary/source compatibility rules, [skill:dotnet-nuget-authoring] for `EnablePackageValidation` and NuGet SemVer, [skill:dotnet-multi-targeting] for multi-TFM ApiCompat tool mechanics, [skill:dotnet-snapshot-testing] for Verify fundamentals, [skill:dotnet-roslyn-analyzers] for general analyzer configuration, [skill:dotnet-api-versioning] for HTTP API versioning.

---

## PublicApiAnalyzers

PublicApiAnalyzers tracks every public API member in text files committed to source control. The analyzer enforces that new APIs go through an explicit "unshipped" phase before being marked "shipped," preventing accidental public API exposure and undocumented surface area changes.

### Setup

Install the analyzer package:

```xml
<ItemGroup>
  <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.*" PrivateAssets="all" />
</ItemGroup>
```

Create the two tracking files at the project root (adjacent to the `.csproj`):

```
MyLib/
  MyLib.csproj
  PublicAPI.Shipped.txt    # APIs shipped in released versions
  PublicAPI.Unshipped.txt  # APIs added since last release
```

Both files must exist, even if empty. Each must contain a header comment:

```
#nullable enable
```

The `#nullable enable` header tells the analyzer to track nullable annotations in API signatures. Without it, nullable context differences are ignored.

### Diagnostic Rules

| Rule | Severity | Meaning |
|------|----------|---------|
| RS0016 | Warning | Public API member not declared in API tracking files |
| RS0017 | Warning | Public API member removed but still in tracking files |
| RS0024 | Warning | Public API member has wrong nullable annotation |
| RS0025 | Warning | Public API symbol marked shipped but has changed signature |
| RS0026 | Warning | New public API added without `PublicAPI.Unshipped.txt` entry |
| RS0036 | Warning | API file missing `#nullable enable` header |
| RS0037 | Warning | Public API declared but does not exist in source |

**RS0016** is the most common diagnostic. When you add a new `public` or `protected` member, RS0016 fires until you add the member's signature to `PublicAPI.Unshipped.txt`. Use the code fix (lightbulb) in the IDE to automatically add the entry.

**RS0017** fires when you remove or rename a `public` member but the old signature still exists in the tracking files. Remove the stale line from the appropriate file.

### File Format

Each line in the tracking files represents one public API symbol using its documentation comment ID format:

```
#nullable enable
MyLib.Widget
MyLib.Widget.Widget() -> void
MyLib.Widget.Name.get -> string!
MyLib.Widget.Name.set -> void
MyLib.Widget.Calculate(int count) -> decimal
MyLib.Widget.CalculateAsync(int count, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Threading.Tasks.Task<decimal>!
MyLib.IWidgetFactory
MyLib.IWidgetFactory.Create(string! name) -> MyLib.Widget!
MyLib.WidgetOptions
MyLib.WidgetOptions.WidgetOptions() -> void
MyLib.WidgetOptions.MaxRetries.get -> int
MyLib.WidgetOptions.MaxRetries.set -> void
```

Key formatting rules:
- The `!` suffix denotes a non-nullable reference type in nullable-enabled context
- The `?` suffix denotes a nullable reference type or nullable value type
- Constructors use the type name (e.g., `Widget.Widget() -> void`)
- Properties expand to `.get` and `.set` entries
- Default parameter values are included in the signature

### Shipped/Unshipped Lifecycle

The workflow across release cycles:

**During development (between releases):**

1. Add new public API member to source code
2. RS0016 fires -- member not tracked
3. Use code fix or manually add to `PublicAPI.Unshipped.txt`
4. RS0016 clears

**At release time:**

1. Move all entries from `PublicAPI.Unshipped.txt` to `PublicAPI.Shipped.txt`
2. Clear `PublicAPI.Unshipped.txt` back to just the `#nullable enable` header
3. Commit both files as part of the release PR
4. Tag the release

**When removing a previously shipped API (major version):**

1. Remove the member from source code
2. Remove the entry from `PublicAPI.Shipped.txt`
3. RS0017 clears (if it fired)
4. Document the removal in release notes

**When removing an unshipped API (before release):**

1. Remove the member from source code
2. Remove the entry from `PublicAPI.Unshipped.txt`
3. No SemVer impact -- the API was never released

### Multi-TFM Projects

For multi-targeted projects, PublicApiAnalyzers supports per-TFM tracking files when the API surface differs across targets:

```
MyLib/
  MyLib.csproj
  PublicAPI.Shipped.txt           # Shared across all TFMs
  PublicAPI.Unshipped.txt         # Shared across all TFMs
  PublicAPI.Shipped.net8.0.txt    # net8.0-specific APIs
  PublicAPI.Unshipped.net8.0.txt  # net8.0-specific APIs
  PublicAPI.Shipped.net10.0.txt   # net10.0-specific APIs
  PublicAPI.Unshipped.net10.0.txt # net10.0-specific APIs
```

The shared files contain APIs common to all TFMs. The TFM-specific files contain APIs that only exist on that target. The analyzer merges them at build time.

To enable per-TFM files, add to the `.csproj`:

```xml
<PropertyGroup>
  <RoslynPublicApiPerTfm>true</RoslynPublicApiPerTfm>
</PropertyGroup>
```

See [skill:dotnet-multi-targeting] for multi-TFM packaging mechanics.

### Integrating with CI

PublicApiAnalyzers runs as part of the standard build. To enforce it in CI, ensure warnings are treated as errors for the RS-series rules:

```xml
<!-- In Directory.Build.props or the library .csproj -->
<PropertyGroup>
  <WarningsAsErrors>$(WarningsAsErrors);RS0016;RS0017;RS0036;RS0037</WarningsAsErrors>
</PropertyGroup>
```

This gates CI builds on any undeclared public API changes. Developers must explicitly update the tracking files before the build passes.

---

## Verify API Surface Snapshot Pattern

Use the Verify library to snapshot-test the entire public API surface of an assembly. This approach uses reflection to enumerate all public types and members, producing a human-readable snapshot that is committed to source control and compared on every test run. Any change to the public API surface causes a test failure until the snapshot is explicitly approved.

This pattern complements PublicApiAnalyzers -- the analyzer catches changes at build time within the project, while the Verify snapshot catches changes from the perspective of a compiled assembly consumer.

For Verify fundamentals (setup, scrubbing, converters, diff tool integration, CI configuration), see [skill:dotnet-snapshot-testing].

### Extracting the Public API Surface

Create a helper method that reflects over an assembly to produce a stable, sorted representation of all public types and their members:

```csharp
using System.Reflection;
usi