Microsoft.DotNet.ApiCompat.Tool 全域工具

發行項
03/13/2024

Microsoft.DotNet.ApiCompat.Tool 工具可讓您在 MSBuild 外部執行 API 相容性檢查。此工具有兩種模式：

比較封裝與基準封裝。
比較組件與基準組件。

安裝

請執行下列命令以安裝工具。

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

如需安裝全域工具的詳細資訊，請參閱安裝全域工具。

使用方式

Microsoft.DotNet.ApiCompat.Tool [command] [options]

-或-

apicompat [command] [options]

命令

package | --package <PACKAGE_FILE>

驗證封裝資產的相容性。如果未指定，此工具會比較組件。 <PACKAGE_FILE> 會指定封裝檔案的路徑。

選項。

某些選項同時適用於組件和封裝驗證。其他選項則是僅限組件或僅限封裝。

一般選項

--version

顯示版本資訊。
--generate-suppression-file

產生相容性歸併檔案。
--preserve-unnecessary-suppressions

在重新產生歸併檔案時，保留不必要的歸併。

重新產生現有的隱藏檔案時，會讀取其內容、還原序列化為一組隱藏，然後儲存在清單中。如果已修正隱藏，可能不再需要某些隱藏。當歸併序列化回到磁碟時，您可以指定此選項以保留所有現有的 (還原序列化) 運算式。
--permit-unnecessary-suppressions

允許歸併檔案中不必要的歸併。
--suppression-file <FILE>

指定一個或多個要讀取的歸併檔案路徑。
--suppression-output-file <FILE>

已指定 --generate-suppression-file 屬性時，指定要寫入歸併檔案的路徑。如果未指定，則會使用第一個 --suppression-file 路徑。
--noWarn <NOWARN_STRING>

指定要歸併的診斷識別碼。例如： "$(NoWarn);PKV0001" 。
--respect-internals

一併檢查 internal 和 public API。
--roslyn-assemblies-path <FILE>

指定目錄的路徑，其中包含您要使用的 Microsoft.CodeAnalysis 組件。只有當您要使用比 SDK 中的編譯器版本更高的編譯器進行測試時，才需要設定此屬性。
-v, --verbosity [high|low|normal]

控制記錄層級的詳細程度。允許的值是 high、normal，以及 low。預設值為 normal。
--enable-rule-cannot-change-parameter-name

啟用規則，以檢查參數名稱是否已在公用方法中變更。
--enable-rule-attributes-must-match

啟用規則，以檢查屬性是否相符。
--exclude-attributes-file <FILE>

指定一個或多個檔案的路徑，其中包含要在 DocId 格式中排除的屬性。

組件專用選項

這些選項僅在比較組件時適用。

-l, --left, --left-assembly <PATH>

指定一或多個組件的路徑，這將放在要比較的左側。比較組件時，必須使用此選項。
-r, --right, --right-assembly <PATH>

指定一或多個組件的路徑，這將放在要比較的右側。比較組件時，必須使用此選項。
--strict-mode

以 strict 模式執行 API 相容性檢查。

封裝專用選項

這些選項僅在比較封裝時適用。

--baseline-package

指定要驗證目前封裝的基準封裝路徑。
--enable-strict-mode-for-compatible-tfms

以 strict 模式驗證 API，適用於所有相容的目標 Framework 合約和實作組件。預設值為 true。
--enable-strict-mode-for-compatible-frameworks-in-package

以 strict 模式驗證 API，適用於根據其目標 Framework 相容的組件。
--enable-strict-mode-for-baseline-validation

以 strict 模式驗證 API 相容性，適用於封裝基準檢查。
--package-assembly-references

指定組件參考的路徑，或封裝中特定目標 Framework 的基礎目錄。以逗號分隔多個值。
--baseline-package-assembly-references

指定組件參考的路徑，或基準封裝中特定目標 Framework 的基礎目錄。以逗號分隔多個值。
--baseline-package-frameworks-to-ignore

指定要在基準封裝中忽略的一系列目標 Framework。架構字串必須完全符合基準套件中的資料夾名稱。

範例

下列命令會比較組件的目前和基準版本。

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

下列命令會比較封裝的目前和基準版本。

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

下列範例顯示用來比較組件目前和基準版本的命令，其中包括檢查參數名稱變更。如果參數名稱已變更，此範例也會顯示輸出將呈現的樣子。

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.

共用方式為

Microsoft.DotNet.ApiCompat.Tool 全域工具

安裝

使用方式

命令

選項。

一般選項

組件專用選項

封裝專用選項

範例

其他資源