組件驗證

發行項
03/19/2024

與套件驗證類似，組件驗證工具可讓身為程式庫開發人員的您，驗證您的組件是否一致且格式正確。當您的應用程式無法封裝時，請使用組件驗證，而非套件驗證。

組件驗證提供下列檢查：

驗證版本之間沒有重大變更。
驗證組件是否針對所有不同執行階段特定實作具有相同的共用 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 目標的一部分)。它也是完全累加的，這表示只有在輸入或輸出變更時才會觸發比較。

範例

建立並建置名為「ValidateMe」的 C# 類別庫，其中包含下列簡單介面：

namespace ValidateMe;

public interface IAnimal
{
    string Name { get; }
    //string Sound { get; }
}

將輸出元件重新命名為「ValidateMeV1.dll」。
Sound藉由取消批注該行程序代碼，將屬性新增至介面。

將 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>

重建類別庫。

組建失敗，並出現下列錯誤：

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'

隱藏相容性警告

如需隱藏相容性警告的相關資訊，請參閱如何隱藏。

共用方式為

組件驗證

啟用 MSBuild 工作

範例

隱藏相容性警告

其他資源