Bagikan melalui

Alat global Microsoft.DotNet.ApiCompat.Tool

  • Artikel

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 dan public 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, dan low. Default adalah normal.

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