API 相容性工具

跨平台相容性已成為 .NET 程式庫作者的主要需求。 不過，如果沒有工具來驗證組件和封裝，其可能就會包含非預期的中斷性變更。 身為程式庫作者，您必須確保多目標組件相容性。 例如，針對 .NET 6 和 .NET Standard 2.0 的多目標封裝，您必須確保 .NET Standard 2.0 二進位所編譯的程式碼可以在 .NET 6 二進位上執行。

如果取用該變更的來源繼續編譯而未變更，則可以認為該變更安全且相容。 不過，如果取用者未重新編譯，變更仍可能會在執行階段造成問題。 例如，將選擇性參數新增至方法或變更常數的值，便可能會導致這類相容性問題。

.NET SDK 提供各種方式供您比較針對不同目標 Framework 建置的版本。 您也可以針對基準版本驗證較新版本，以確保不會引進任何中斷性變更。 啟用 MSBuild 工作以在編譯時間驗證您的組件，或於封裝時驗證您的封裝。 或者，您可以使用 Microsoft.DotNet.ApiCompat.Tool 全域工具在 MSBuild 外部進行驗證。

如需驗證封裝的詳細資訊，請參閱封裝驗證。當您的應用程式無法封裝時，則應使用組件驗證。 如需組件驗證的詳細資訊，請參閱組件驗證。

注意

若要以 MSBuild 工作的形式執行組件驗證，您必須將封裝參考新增至 Microsoft.DotNet.ApiCompat.Task。 同樣地，當您想要測試 .NET SDK 中尚未提供的新功能時，您也可以將參考新增至此封裝。 例如，您可以在使用 .NET 8 SDK 時參考 Microsoft.DotNet.ApiCompat.Task 封裝的 9.0.100-preview 版本。

Strict 模式

根據預設，驗證會執行相容性檢查。 不過，您也可以加入 strict 模式。 在 strict 模式中，驗證會 執行相 等檢查。 相等表示沒有增加任何 API 或組件變更，這也包括沒有變更為相容的 API。

strict 模式的使用案例包括下列項目：

• 服務，這通常會禁止增加 API。
• 用於追蹤 API 變更。 如果您將 ApiCompatGenerateSuppressionFile 設定為 true，API 相容性功能會記錄歸併檔案中的所有相容性差異。

若要啟用命令列工具的 strict 模式，請指定 --strict-mode 選項或其中一個 --enable-strict* 選項。 若要啟用 MSBuild 工作的 strict 模式，請將下列一個或多個 MSBuild 屬性新增至您的專案檔：

• ApiCompatStrictMode
• EnableStrictModeForBaselineValidation
• EnableStrictModeForCompatibleTfms
• EnableStrictModeForCompatibleFrameworksInPackage