Alat global Microsoft.DotNet.ApiCompat.Tool
Alat Microsoft.DotNet.ApiCompat.Tool memungkinkan Anda melakukan pemeriksaan kompatibilitas API di luar MSBuild. Alat ini memiliki dua mode:
- Bandingkan paket dengan paket dasar.
- Bandingkan rakitan dengan rakitan garis besar.
Instal
Untuk menginstal alat, jalankan perintah berikut.
dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool
Untuk informasi selengkapnya tentang menginstal alat global, lihat Menginstal alat global.
Penggunaan
Microsoft.DotNet.ApiCompat.Tool [command] [options]
-atau-
apicompat [command] [options]
Perintah
package | --package <PACKAGE_FILE>
Memvalidasi kompatibilitas aset paket. Jika tidak ditentukan, alat membandingkan rakitan.
<PACKAGE_FILE>
menentukan jalur ke file paket.
Opsi
Beberapa opsi berlaku untuk validasi rakitan dan paket. Yang lain hanya berlaku untuk rakitan atau paket.
Opsi Umum
--version
Memperlihatkan informasi versi.
--generate-suppression-file
Menghasilkan file supresi kompatibilitas.
--preserve-unnecessary-suppressions
Mempertahankan supresi yang tidak perlu saat meregenerasi file supresi.
Ketika file supresi yang ada diregenerasi, kontennya dibaca, dideserialisasi ke dalam serangkaian supresi, lalu disimpan dalam daftar. Beberapa supresi mungkin tidak lagi diperlukan jika ketidaksesuaian telah diperbaiki. Ketika supresi diserialisasikan kembali ke disk, Anda dapat memilih untuk menyimpan semua ekspresi (deserialisasi) yang ada dengan menentukan opsi ini.
--permit-unnecessary-suppressions
Mengizinkan supresi yang tidak perlu dalam file supresi.
--suppression-file <FILE>
Menentukan jalur ke satu atau beberapa file supresi untuk dibaca.
--suppression-output-file <FILE>
Menentukan jalur ke file supresi yang akan ditulis ketika
--generate-suppression-file
ditentukan. Jika tidak ditentukan, jalur pertama--suppression-file
digunakan.--noWarn <NOWARN_STRING>
Menentukan ID diagnostik untuk ditekan. Contohnya,
"$(NoWarn);PKV0001"
.--respect-internals
Memeriksa API
internal
danpublic
api.--roslyn-assemblies-path <FILE>
Menentukan jalur ke direktori yang berisi rakitan Microsoft.CodeAnalysis yang ingin Anda gunakan. Anda hanya perlu mengatur properti ini jika Anda ingin menguji dengan pengkompilasi yang lebih baru daripada apa yang ada di SDK.
-v, --verbosity [high|low|normal]
Mengontrol verbositas tingkat log. Nilai yang diizinkan adalah
high
,normal
, danlow
. Default adalahnormal
.--enable-rule-cannot-change-parameter-name
Mengaktifkan aturan yang memeriksa apakah nama parameter telah berubah dalam metode publik.
--enable-rule-attributes-must-match
Mengaktifkan aturan yang memeriksa apakah atribut cocok.
--exclude-attributes-file <FILE>
Menentukan jalur ke satu atau beberapa file yang berisi atribut untuk dikecualikan dalam format DocId .
Opsi khusus perakitan
Opsi ini hanya berlaku jika rakitan dibandingkan.
-l, --left, --left-assembly <PATH>
Menentukan jalur ke satu atau beberapa rakitan yang berfungsi sebagai sisi kiri untuk dibandingkan. Opsi ini diperlukan saat membandingkan rakitan.
-r, --right, --right-assembly <PATH>
Menentukan jalur ke satu atau beberapa rakitan yang berfungsi sebagai sisi kanan untuk dibandingkan. Opsi ini diperlukan saat membandingkan rakitan.
--strict-mode
Melakukan pemeriksaan kompatibilitas API dalam mode ketat.
Opsi khusus paket
Opsi ini hanya berlaku ketika paket dibandingkan.
--baseline-package
Menentukan jalur ke paket garis besar untuk memvalidasi paket saat ini.
--enable-strict-mode-for-compatible-tfms
Memvalidasi kompatibilitas API dalam mode ketat untuk rakitan kontrak dan implementasi untuk semua kerangka kerja target yang kompatibel. Default adalah
true
.--enable-strict-mode-for-compatible-frameworks-in-package
Memvalidasi kompatibilitas API dalam mode ketat untuk rakitan yang kompatibel berdasarkan kerangka kerja targetnya.
--enable-strict-mode-for-baseline-validation
Memvalidasi kompatibilitas API dalam mode ketat untuk pemeriksaan garis besar paket.
--package-assembly-references
Menentukan jalur ke referensi perakitan atau direktori yang mendasarnya untuk kerangka kerja target tertentu dalam paket. Pisahkan beberapa nilai dengan koma.
--baseline-package-assembly-references
Menentukan jalur ke referensi perakitan atau direktori dasarnya untuk kerangka kerja target tertentu dalam paket dasar . Pisahkan beberapa nilai dengan koma.
--baseline-package-frameworks-to-ignore
Menentukan kumpulan kerangka kerja target yang akan diabaikan dari paket garis besar. String kerangka kerja harus sama persis dengan nama folder dalam paket garis besar.
Contoh
Perintah berikut membandingkan versi rakitan saat ini dan garis besar.
apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll
Perintah berikut membandingkan versi paket saat ini dan garis besar.
apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"
Contoh berikut menunjukkan perintah untuk membandingkan versi rakitan saat ini dan garis besar, termasuk pemeriksaan perubahan nama parameter. Contohnya juga menunjukkan tampilan output jika nama parameter telah berubah.
>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.