Share via

Alat kompatibilitas API

  • Artikel

Kompatibilitas lintas platform telah menjadi persyaratan utama bagi penulis pustaka .NET. Namun, tanpa alat untuk memvalidasi rakitan dan paket, mereka mungkin berisi perubahan melanggar yang tidak disengaja. Sebagai penulis pustaka, Anda perlu memastikan bahwa rakitan multi-target kompatibel. Misalnya, untuk paket yang multi-target untuk .NET 6 dan .NET Standard 2.0, Anda harus memastikan bahwa kode yang dikompilasi terhadap biner .NET Standard 2.0 dapat berjalan terhadap biner .NET 6.

Anda mungkin berpikir bahwa perubahan aman dan kompatibel jika sumber yang mengkonsumsi perubahan tersebut terus dikompilasi tanpa perubahan. Namun, perubahan masih dapat menyebabkan masalah pada run time jika konsumen tidak dikompresi ulang. Misalnya, menambahkan parameter opsional ke metode atau mengubah nilai konstanta dapat menyebabkan masalah kompatibilitas semacam ini.

.NET SDK menyediakan berbagai cara untuk membandingkan versi yang dibuat untuk kerangka kerja target yang berbeda. Anda juga dapat memvalidasi versi yang lebih baru terhadap versi dasar untuk memastikan tidak ada perubahan yang melanggar yang telah diperkenalkan. Aktifkan tugas MSBuild untuk memvalidasi rakitan Anda pada waktu kompilasi atau paket Anda saat Anda mengemas. Atau, gunakan alat global Microsoft.DotNet.ApiCompat.Tool untuk memvalidasi di luar MSBuild.

Untuk informasi selengkapnya tentang validasi paket, lihat Validasi paket. Validasi rakitan harus digunakan saat aplikasi Anda tidak dapat dikemas. Untuk informasi selengkapnya tentang validasi perakitan, lihat Validasi perakitan.

Catatan

Untuk menjalankan validasi rakitan sebagai tugas MSBuild, Anda harus menambahkan referensi paket ke Microsoft.DotNet.ApiCompat.Task. Demikian pula, Anda juga dapat menambahkan referensi ke paket ini ketika Anda ingin menguji fitur yang lebih baru yang belum tersedia di .NET SDK. Misalnya, Anda dapat mereferensikan versi pratinjau 9.0.100 dari paket Microsoft.DotNet.ApiCompat.Task saat menggunakan .NET 8 SDK.

Mode ketat

Secara default, validasi melakukan pemeriksaan kompatibilitas . Namun, Anda juga dapat memilih mode ketat. Dalam mode ketat, validasi melakukan pemeriksaan kesetaraan . Kesetaraan berarti bahwa tidak ada penambahan API atau perubahan rakitan, bahkan yang kompatibel, yang telah dibuat.

Kasus penggunaan untuk mode ketat mencakup yang berikut ini:

  • Layanan, di mana penambahan API biasanya dilarang.
  • Untuk melacak perubahan API. Fungsionalitas kompatibilitas API mencatat semua perbedaan kompatibilitas dalam file supresi jika Anda mengatur ApiCompatGenerateSuppressionFile ke true.

Untuk mengaktifkan mode ketat untuk alat baris perintah, tentukan --strict-mode opsi atau salah --enable-strict* satu opsi. Untuk mengaktifkan mode ketat untuk tugas MSBuild, tambahkan satu atau beberapa properti MSBuild berikut ke file proyek Anda: