アセンブリの検証

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

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

• バージョン間で破壊的な変更がないことを検証します。
• ランタイム固有のすべての実装に対して、アセンブリに同じパブリック 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. ApiCompatValidateAssemblies と ApiCompatContractAssembly プロパティ、および "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'
   

互換性の警告を抑制する

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