Microsoft.DotNet.ApiCompat.Tool globális eszköz

Cikk
12/05/2023

A Microsoft.DotNet.ApiCompat.Tool eszközzel api-kompatibilitási ellenőrzéseket hajthat végre az MSBuilden kívül. Az eszköznek két módja van:

Egy csomag összehasonlítása egy alapcsomagtal.
Szerelvény összehasonlítása az alapkonfigurációs szerelvénysel.

Telepítés

Az eszköz telepítéséhez futtassa a következő parancsot.

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

A globális eszközök telepítésével kapcsolatos további információkért lásd : Globális eszköz telepítése.

Használat

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

-vagy-

apicompat [command] [options]

Parancsok

package | --package <PACKAGE_FILE>

Ellenőrzi a csomagegységek kompatibilitását. Ha nincs meghatározva, az eszköz összehasonlítja a szerelvényeket. <PACKAGE_FILE> a csomagfájl elérési útját adja meg.

Beállítások

Egyes beállítások a szerelvényre és a csomag érvényesítésére is érvényesek. Mások csak szerelvényekre vagy csomagokra vonatkoznak.

Általános beállítások

--version

A verzióinformációkat jeleníti meg.
--generate-suppression-file

Kompatibilitás-letiltó fájlt hoz létre.
--preserve-unnecessary-suppressions

Megőrzi a szükségtelen elnyomásokat a letiltó fájl újragenerálásakor.

Egy meglévő letiltó fájl újragenerálásakor a rendszer felolvassa annak tartalmát, deszerializálja az elnyomások egy csoportjába, majd egy listában tárolja. Előfordulhat, hogy az inkompatibilitás kijavítása esetén a továbbiakban nem lesz szükség a letiltásokra. Ha a letiltások vissza lettek szerializálva a lemezre, a beállítás megadásával megadhatja, hogy az összes meglévő (deszerializált) kifejezés megmaradjon.
--permit-unnecessary-suppressions

Engedélyezi a szükségtelen elnyomásokat a letiltási fájlban.
--suppression-file <FILE>

Egy vagy több elnyomási fájl elérési útját adja meg, amelyből olvasni szeretne.
--suppression-output-file <FILE>

Megadja egy letiltó fájl elérési útját, amelybe írható, amikor --generate-suppression-file meg van adva. Ha nincs meghatározva, a rendszer az első --suppression-file elérési utat használja.
--noWarn <NOWARN_STRING>

Megadja a letiltani kívánt diagnosztikai azonosítókat. Például: "$(NoWarn);PKV0001".
--respect-internals

Mindkettőt és public AZ API-kat is internal ellenőrzi.
--roslyn-assemblies-path <FILE>

Megadja a használni kívánt Microsoft.CodeAnalysis-szerelvényeket tartalmazó könyvtár elérési útját. Ezt a tulajdonságot csak akkor kell beállítania, ha az SDK-ban találhatónál újabb fordítóval szeretne tesztelni.
-v, --verbosity [high|low|normal]

Szabályozza a naplószintű részletességet. Az engedélyezett értékek a következőkhigh: és lownormal. Az alapértelmezett érték normal.
--enable-rule-cannot-change-parameter-name

Engedélyezi azt a szabályt, amely ellenőrzi, hogy a paraméternevek megváltoztak-e a nyilvános metódusokban.
--enable-rule-attributes-must-match

Engedélyezi azt a szabályt, amely ellenőrzi, hogy az attribútumok egyeznek-e.
--exclude-attributes-file <FILE>

Megadja egy vagy több olyan fájl elérési útját, amely docId formátumban kizárandó attribútumokat tartalmaz.

Szerelvényspecifikus beállítások

Ezek a lehetőségek csak a szerelvények összehasonlítása esetén alkalmazhatók.

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

Egy vagy több szerelvény elérési útját adja meg, amelyek a bal oldalon szolgálnak az összehasonlításhoz. Ez a beállítás a szerelvények összehasonlítása során szükséges.
-r, --right, --right-assembly <PATH>

Egy vagy több szerelvény elérési útját adja meg, amelyek a jobb oldalon szolgálnak az összehasonlításhoz. Ez a beállítás a szerelvények összehasonlítása során szükséges.
--strict-mode

Szigorú módban hajtja végre az API kompatibilitási ellenőrzését.

Csomagspecifikus beállítások

Ezek a lehetőségek csak a csomagok összehasonlítása esetén alkalmazhatók.

--baseline-package

Megadja az alapcsomag elérési útját az aktuális csomag ellenőrzéséhez.
--enable-strict-mode-for-compatible-tfms

Ellenőrzi az API-kompatibilitást szigorú módban az összes kompatibilis cél-keretrendszerhez tartozó szerződés- és implementációs szerelvényekhez. Az alapértelmezett érték true.
--enable-strict-mode-for-compatible-frameworks-in-package

Szigorú módban ellenőrzi az API-kompatibilitást olyan szerelvények esetében, amelyek kompatibilisek a cél keretrendszerük alapján.
--enable-strict-mode-for-baseline-validation

Szigorú módban ellenőrzi az API-kompatibilitást a csomag alapkonfiguráció-ellenőrzéséhez.
--package-assembly-references

Megadja a csomag egy adott cél keretrendszeréhez tartozó szerelvényhivatkozások vagy azok mögöttes könyvtárainak elérési útját. Több érték elkülönítése vesszővel.
--baseline-package-assembly-references

Meghatározza a szerelvényhivatkozások elérési útját vagy azok mögöttes könyvtárait az alapcsomag egy adott célkeretéhez. Több érték elkülönítése vesszővel.
--baseline-package-frameworks-to-ignore

Megadja az alapcsomagból figyelmen kívül hagyandó cél-keretrendszerek készletét. A keretrendszer sztringjének pontosan meg kell egyeznie az alapcsomag mappanevével.

Példák

Az alábbi parancs egy szerelvény aktuális és alapkonfigurációs verzióit hasonlítja össze.

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

Az alábbi parancs összehasonlítja egy csomag aktuális és alapkonfigurációs verzióit.

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

Az alábbi példa egy szerelvény aktuális és alapverzióinak összehasonlítására szolgáló parancsot mutatja be, beleértve a paraméternévváltozások ellenőrzését is. A példa azt is bemutatja, hogy hogyan nézhet ki a kimenet, ha egy paraméter neve megváltozott.

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

Megosztás a következőn keresztül: