.NET: Set up PublicAPI analyzers and shipped API promotion #7933

Summary

The .NET projects currently do not appear to use Microsoft.CodeAnalysis.PublicApiAnalyzers or PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt baselines. We should consider setting them up for released packages so public API changes are explicitly reviewed, tracked, and promoted as part of the release process.

Proposal

1. Add Public API Analyzer support to released .NET packages.

   • Add the analyzer package/configuration needed to enforce public API baselines.
   • Add PublicAPI.Shipped.txt and PublicAPI.Unshipped.txt files for packages that publish public APIs.
   • Establish guidance for contributors: new public APIs go into PublicAPI.Unshipped.txt; breaking/removal changes are intentional and reviewed.

2. Add an automatic shipped API promotion workflow.

   • Use a workflow similar to microsoft/OpenAPI.NET's promote-shipped-apis.yml: https://github.com/microsoft/OpenAPI.NET/blob/main/.github/workflows/promote-shipped-apis.yml
   • On pushes to release branches and/or manual dispatch, move entries from PublicAPI.Unshipped.txt to PublicAPI.Shipped.txt and open/update a PR.
   • This keeps API baselines current without making release managers manually promote each entry.

3. Update release workflows to fail when unshipped public API entries remain.

   • Before publishing packages, validate that PublicAPI.Unshipped.txt files are empty or absent.
   • This prevents releasing packages with APIs that were added but never promoted into the shipped baseline.

Benefits

• Makes public API changes visible in PRs instead of relying on reviewers to notice new public types, members, constants, or accessibility changes.
• Helps distinguish intentional API additions from accidental public surface area exposure.
• Creates an auditable history of shipped APIs for released packages.
• Makes release readiness clearer by separating unshipped API work from APIs that have been accepted into the shipped contract.
• Reduces reviewer burden when public APIs are added across multiple projects or target frameworks.

Risks addressed

• Accidentally shipping new public APIs without design/API review.
• Accidentally changing or removing public APIs in ways that may break consumers.
• Forgetting to promote accepted APIs before release.
• Inconsistent API baseline practices across packages.
• Discovering API-surface problems late in the release pipeline instead of during PR validation.

Notes

This is especially useful for released packages where even small additions, such as public constants used as metadata keys, become part of the supported surface area once published.