アセンブリの検証

パッケージ検証と同様に、アセンブリ検証ツールを使用すると、ライブラリ開発者は、パッケージが一貫性のある適切な形式であることを検証できます。 アプリがパックできない場合は、パッケージ検証の代わりにアセンブリ検証を使用します。

アセンブリ検証では、次のチェックが提供されます。

  • バージョン間で破壊的な変更がないことを検証します。
  • ランタイム固有のすべての実装に対して、アセンブリに同じパブリック API のセットがあることを検証します。
  • 適応性の抜けをキャッチします。

アセンブリ検証は、MSBuild タスクとして、または Microsoft.DotNet.ApiCompat.Tool グローバル ツールを使用して実行することができます。

MSBuild タスクを有効にする

.NET プロジェクトでアセンブリ検証を有効にするには、ApiCompatValidateAssemblies プロパティを true に設定し、コントラクト (ベースライン) アセンブリへのパスを指定します。 また、Microsoft.DotNet.ApiCompat.Task へのパッケージ参照を追加する必要もあります。 (そのパッケージ内の targets ファイルは .NET SDK の一部ではありません)。

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>net8.0</TargetFrameworks>
    <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
    <ApiCompatContractAssembly>[Path to contract assembly]</ApiCompatContractAssembly>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
    <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
  </ItemGroup>

</Project>

アセンブリ検証は、マルチターゲット プロジェクトの外部ビルド (DispatchToInnerBuilds ターゲットの後) または単一ターゲット プロジェクトの内部ビルド (PrepareForRun ターゲットの一部として) で実行されます。 また、これは完全に増分です。つまり、入力または出力が変更された場合にのみ比較がトリガーされます。

  1. 次の単純なインターフェイスを含む "ValidateMe" という名前の C# クラス ライブラリを作成してビルドします。

    namespace ValidateMe;
    
    public interface IAnimal
    {
        string Name { get; }
        //string Sound { get; }
    }
    
  2. 出力アセンブリの名前を "ValidateMeV1.dll" に変更します。

  3. そのコード行のコメントを解除して、インターフェイスに Sound プロパティを追加します。

  4. ApiCompatValidateAssembliesApiCompatContractAssembly プロパティ、および "Microsoft.DotNet.ApiCompat.Task" パッケージ参照をプロジェクト ファイルに追加します。 また、アセンブリのバージョンを "2.0.0" にインクリメントします。

    <PropertyGroup>
      <OutputType>Library</OutputType>
      <TargetFrameworks>net8.0</TargetFrameworks>
      <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
      <ApiCompatContractAssembly>$(OutDir)bin\Release\net8.0\ValidateMeV1.dll</ApiCompatContractAssembly>
      <IsPackable>false</IsPackable>
      <Version>2.0.0</Version>
    </PropertyGroup>
    
    <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
       <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
    </ItemGroup>
    
  5. クラス ライブラリをリビルドします。

    次のエラーによりビルドが失敗しました:

    C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API compatibility errors between 'bin\Release\net8.0\ValidateMeV1.dll' (left) and 'C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll' (right):
    1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error CP0006: Cannot add interface member 'string ValidateMe.IAnimal.Sound' to C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll because it does not exist on bin\Release\net8.0\ValidateMeV1.dll
    1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API breaking changes found. If those are intentional, the APICompat suppression file can be updated by rebuilding with '/p:ApiCompatGenerateSuppressionFile=true'
    

互換性の警告を抑制する

互換性の警告の抑制については、抑制方法に関する記述を参照してください。