Migrate to .NET Package Validation

[heaths]

We're using an old Microsoft.DotNet.ApiCompat package that doesn't evaluate compatible targets, and our own logic in eng/Directory.Build.Common.Targets below is currently causing issues like #33431:

  <Target Name="_ResolveResolvedMatchingContract" BeforeTargets="ValidateApiCompatForSrc" Condition="'$(ApiCompatVersion)' != ''">
    <ItemGroup>
      <_ReferencePathDirectories Include="@(ReferencePath -> '%(RootDir)%(Directory)')"  />
      <ResolvedMatchingContract Include="$(NuGetPackageRoot)\$(PackageId.ToLower())\$(ApiCompatVersion)\lib\$(TargetFramework)\$(TargetFileName)">
        <DependencyPaths>@(_ReferencePathDirectories->Distinct(), ',')</DependencyPaths>
      </ResolvedMatchingContract>
    </ItemGroup>
  </Target>

It was recommended to switch to built-in package validation now that we're moving to net7.0.

This will require some changes to any exceptions we have, so something we probably want to do only when working on changing all packages for #32597.

• Remove old Microsoft.DotNet.ApiCompat package
• Migrate any exceptions to the new format
• Rename <ApiCompatVersion> and updating tooling, OR
• Add <Target> to use <ApiCompatVersion> to define whatever property the built-in validation needs.

[heaths]

/cc @JoshLove-msft @hallipr @weshaggard

[heaths]

Be sure to take advantage of the cross-platform, cross-framework API checks as described.

[heaths]

There may be some problems:

1. Can't find anything that would effectively ignore certain attributes being added or removed from a definition like we use now with Microsoft.DotNet.ApiCompat: <ApiCompatExcludeAttributeList>$(MSBuildThisFileDirectory)ApiListing.exclude-attributes.txt</ApiCompatExcludeAttributeList>
2. Similarly, Microsoft.DotNet.GenAPI is also not published to nuget.org and a similar one had only one release and is deprecated. That generates the **/api/*.netstandard2.0.cs files we emit and compare in PRs.
3. I imagine APIView relies partly on being informed about violations in a particular way, or even builds the RunApiCompat target, which is now all done during the Pack target e.g., dotnet pack.

To upgrade, we may need to rethink our whole stack.

/cc @JoshLove-msft @hallipr

[heaths]

I got some answers back from the .NET team that are relevant here:

To just run validation, you can install a global tool:

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool --version --prerelease

However, they state,

Note that I would not use the CLI frontend if you already operate in an msbuild environment. Reason for that:

• Assembly references need to be passed in manually which msbuild targets already do for you.
• Package baseline validation in msbuild handles downloading the baseline package (with a given baseline version) and passing it in.
• You need an extra tool. APICompat’s msbuild frontend is part of the .NET SDK and can just be enabled via a property.
• It’s currently undocumented and based on the download numbers not much used. Expect rough edges and bugs.

Additionally,

Using the msbuild flavor of ApiCompat only requires enabling a few settings inside an msbuild environment as documented (.NET Package Validation - .NET | Microsoft Learn):

<PropertyGroup>
  <EnablePackageValidation>true</EnablePackageValidation>
</PropertyGroup>

If you want to enable baseline package validation as well, set the following property. “x.x.x” refers to the version that you want to compare the just generated package against.

<PropertyGroup>
  <PackageValidationBaselineVersion>x.x.x</PackageValidationBaselineVersion>
</PropertyGroup>

Here are some additional settings for the msbuild frontend:

<PropertyGroup>
  <!—Enable attribute comparison optional rule. -->
  <ApiCompatEnableRuleAttributesMustMatch>true</ApiCompatEnableRuleAttributesMustMatch>
  <!—Enable cannot change parameter names optional rule. -->
  <ApiCompatEnableRuleCannotChangeParameterName>true</ApiCompatEnableRuleCannotChangeParameterName>
  <!—Perform validation in strict mode. This setting enforces public API in left (baseline) and right (current) to be strictly equal. This setting is usually only enabled during servicing in which public API shouldn’t change. -->
  <ApiCompatStrictMode>true</ApiCompatStrictMode>
</PropertyGroup>

<ItemGroup>
  <ApiCompatExcludeAttributesFile Include=”<path-to-doc-ids.txt>” />
</ItemGroup>

So we can still use our $(MSBuildThisFileDirectory)ApiListing.exclude-attributes.txt file.