Kelas System.Runtime.Versioning.ComponentGuaranteesAttribute

Artikel
01/08/2024

Artikel ini menyediakan keterangan tambahan untuk dokumentasi referensi untuk API ini.

digunakan ComponentGuaranteesAttribute oleh pengembang komponen dan pustaka kelas untuk menunjukkan tingkat kompatibilitas yang dapat diharapkan konsumen pustaka mereka di beberapa versi. Ini menunjukkan tingkat jaminan bahwa versi pustaka atau komponen di masa mendatang tidak akan merusak klien yang ada. Klien kemudian dapat menggunakan ComponentGuaranteesAttribute sebagai bantuan dalam merancang antarmuka mereka sendiri untuk memastikan stabilitas di seluruh versi.

Catatan

Runtime bahasa umum (CLR) tidak menggunakan atribut ini dengan cara apa pun. Nilainya terletak pada dokumentasi resmi niat penulis komponen. Alat waktu kompilasi juga dapat menggunakan deklarasi ini untuk mendeteksi kesalahan waktu kompilasi yang jika tidak akan merusak jaminan yang dinyatakan.

Tingkat kompatibilitas

Mendukung ComponentGuaranteesAttribute tingkat kompatibilitas berikut, yang diwakili oleh anggota ComponentGuaranteesOptions enumerasi:

Tidak ada kompatibilitas versi ke versi (ComponentGuaranteesOptions.None). Klien dapat mengharapkan bahwa versi di masa mendatang akan merusak klien yang ada. Untuk informasi selengkapnya, lihat bagian Tidak ada kompatibilitas nanti di artikel ini.
Kompatibilitas versi ke versi berdampingan (ComponentGuaranteesOptions.SideBySide). Komponen telah diuji untuk bekerja ketika lebih dari satu versi rakitan dimuat di domain aplikasi yang sama. Secara umum, versi mendatang dapat merusak kompatibilitas. Namun, ketika perubahan melanggar dilakukan, versi lama tidak dimodifikasi tetapi ada bersama versi baru. Eksekusi berdampingan adalah cara yang diharapkan untuk membuat klien yang ada berfungsi saat melanggar perubahan dilakukan. Untuk informasi selengkapnya, lihat bagian Kompatibilitas berdampingan nanti di artikel ini.
Kompatibilitas versi ke versi yang stabil (ComponentGuaranteesOptions.Stable). Versi mendatang tidak boleh merusak klien, dan eksekusi berdampingan seharusnya tidak diperlukan. Namun, jika klien secara tidak sengaja rusak, mungkin untuk menggunakan eksekusi berdampingan untuk memperbaiki masalah. Untuk informasi selengkapnya, lihat bagian Kompatibilitas stabil.
Kompatibilitas versi ke versi Exchange (ComponentGuaranteesOptions.Exchange). Perawatan luar biasa diambil untuk memastikan bahwa versi di masa mendatang tidak akan merusak klien. Klien hanya boleh menggunakan jenis ini dalam tanda tangan antarmuka yang digunakan untuk komunikasi dengan rakitan lain yang disebarkan secara independen satu sama lain. Hanya satu versi jenis ini yang diharapkan berada di domain aplikasi tertentu, yang berarti bahwa jika klien berhenti, eksekusi berdampingan tidak dapat memperbaiki masalah kompatibilitas. Untuk informasi selengkapnya, lihat bagian kompatibilitas jenis Exchange.

Bagian berikut membahas setiap tingkat jaminan secara lebih rinci.

Tidak ada kompatibilitas

Menandai komponen sebagai ComponentGuaranteesOptions.None menunjukkan bahwa penyedia tidak memberikan jaminan tentang kompatibilitas. Klien harus menghindari mengambil dependensi apa pun pada antarmuka yang diekspos. Tingkat kompatibilitas ini berguna untuk jenis yang bersifat eksperimental atau yang diekspos secara publik tetapi hanya ditujukan untuk komponen yang selalu diperbarui pada saat yang sama. None secara eksplisit menunjukkan bahwa komponen ini tidak boleh digunakan oleh komponen eksternal.

Kompatibilitas berdampingan

Menandai komponen sebagai ComponentGuaranteesOptions.SideBySide menunjukkan bahwa komponen telah diuji untuk bekerja ketika lebih dari satu versi rakitan dimuat ke dalam domain aplikasi yang sama. Perubahan yang melanggar diizinkan selama dibuat ke rakitan yang memiliki nomor versi yang lebih besar. Komponen yang terikat ke versi lama rakitan diharapkan untuk terus mengikat ke versi lama, dan komponen lain dapat mengikat ke versi baru. Dimungkinkan juga untuk memperbarui komponen yang dinyatakan dengan SideBySide memodifikasi versi lama secara destruktif.

Kompatibilitas yang stabil

Menandai jenis sebagai ComponentGuaranteesOptions.Stable menunjukkan bahwa jenis harus tetap stabil di seluruh versi. Namun, mungkin juga versi berdampingan dari jenis stabil ada di domain aplikasi yang sama.

Jenis stabil mempertahankan bilah kompatibilitas biner yang tinggi. Karena itu, penyedia harus menghindari membuat perubahan yang melanggar pada jenis stabil. Jenis perubahan berikut dapat diterima:

Menambahkan bidang instans privat ke, atau menghapus bidang dari, jenis, selama ini tidak merusak format serialisasi.
Mengubah jenis yang tidak dapat diserialisasikan ke jenis yang dapat diserialisasikan. (Namun, jenis yang dapat diserialisasikan tidak dapat diubah ke jenis yang tidak dapat diserialisasikan.)
Melemparkan pengecualian baru yang lebih turunan dari metode .
Meningkatkan performa metode.
Mengubah rentang nilai pengembalian, selama perubahan tidak berdampak buruk pada sebagian besar klien.
Memperbaiki bug serius, jika pembenaran bisnis tinggi dan jumlah klien yang terkena dampak buruk rendah.

Karena versi baru komponen stabil tidak diharapkan untuk memutus klien yang ada, umumnya hanya satu versi komponen stabil yang diperlukan dalam domain aplikasi. Namun, ini bukan persyaratan, karena jenis stabil tidak digunakan sebagai jenis pertukaran terkenal yang disepakati semua komponen. Oleh karena itu, jika versi baru komponen stabil secara tidak sengaja merusak beberapa komponen, dan jika komponen lain membutuhkan versi baru, mungkin untuk memperbaiki masalah dengan memuat komponen lama dan baru.

Stable memberikan jaminan kompatibilitas versi yang lebih kuat daripada None. Ini adalah default umum untuk komponen multi-versi.

Stable dapat dikombinasikan dengan SideBySide, yang menyatakan bahwa komponen tidak akan merusak kompatibilitas tetapi diuji untuk bekerja ketika lebih dari satu versi dimuat dalam domain aplikasi tertentu.

Setelah jenis atau metode ditandai sebagai Stable, metode dapat ditingkatkan ke Exchange. Namun, itu tidak dapat diturunkan ke None.

Kompatibilitas jenis Exchange

Menandai jenis sebagai ComponentGuaranteesOptions.Exchange memberikan jaminan kompatibilitas versi yang lebih kuat daripada Stable, dan harus diterapkan ke yang paling stabil dari semua jenis. Jenis ini dimaksudkan untuk digunakan untuk pertukaran antara komponen yang dibangun secara independen di semua batas komponen dalam kedua waktu (versi CLR atau versi apa pun dari komponen atau aplikasi) dan ruang (lintas proses, lintas CLR dalam satu proses, domain lintas aplikasi dalam satu CLR). Jika perubahan yang melanggar dilakukan pada jenis pertukaran, tidak mungkin untuk memperbaiki masalah dengan memuat beberapa versi jenis.

Jenis pertukaran harus diubah hanya ketika masalah sangat serius (seperti masalah keamanan yang parah) atau kemungkinan kerusakan sangat rendah (yaitu, jika perilaku sudah rusak dengan cara acak kode tersebut tidak mungkin mengambil dependensi). Anda dapat membuat jenis perubahan berikut pada jenis pertukaran:

Tambahkan pewarisan definisi antarmuka baru.
Tambahkan metode privat baru yang mengimplementasikan metode definisi antarmuka yang baru diwariskan.
Tambahkan bidang statis baru.
Tambahkan metode statis baru.
Tambahkan metode instans non-virtual baru.

Berikut ini dianggap melanggar perubahan dan tidak diizinkan untuk jenis primitif:

Mengubah format serialisasi. Serialisasi toleran versi diperlukan.
Menambahkan atau menghapus bidang instans privat. Risiko ini mengubah format serialisasi jenis dan melanggar kode klien yang menggunakan pantulan.
Mengubah serialisasi jenis. Jenis yang tidak dapat diserialisasikan mungkin tidak dapat diserialisasikan, dan sebaliknya.
Melemparkan pengecualian yang berbeda dari metode .
Mengubah rentang nilai pengembalian metode, kecuali definisi anggota meningkatkan kemungkinan ini dan dengan jelas menunjukkan bagaimana klien harus menangani nilai yang tidak diketahui.
Memperbaiki sebagian besar bug. Konsumen jenis akan mengandalkan perilaku yang ada.

Setelah komponen, jenis, atau anggota ditandai dengan Exchange jaminan, komponen tidak dapat diubah menjadi Stable atau None.

Biasanya, jenis pertukaran adalah jenis dasar (seperti Int32 dan String di .NET) dan antarmuka (seperti IList<T>, , IEnumerable<T>dan IComparable<T>) yang umumnya digunakan dalam antarmuka publik.

Jenis Exchange hanya dapat mengekspos jenis lain yang juga ditandai dengan Exchange kompatibilitas. Selain itu, jenis pertukaran tidak dapat bergantung pada perilaku API Windows yang rentan berubah.

Jaminan komponen

Tabel berikut menunjukkan bagaimana karakteristik dan penggunaan komponen memengaruhi jaminan kompatibilitasnya.

Karakteristik komponen	Exchange	Stabil	Berdampingan	Tidak
Dapat digunakan dalam antarmuka antara komponen yang versinya secara independen.	Y	N	N	N
Dapat digunakan (secara privat) oleh rakitan yang versinya secara independen.	Y	Y	Y	N
Dapat memiliki beberapa versi dalam satu domain aplikasi.	N	Y	Y	Y
Dapat membuat perubahan yang melanggar	N	N	Y	Y
Diuji untuk membuat beberapa versi assembly tertentu dapat dimuat bersama-sama.	N	N	Y	N
Dapat membuat perubahan yang melanggar di tempat.	N	N	N	Y
Dapat membuat perubahan layanan non-melanggar yang sangat aman di tempat.	Y	Y	Y	Y

Terapkan atribut

Anda dapat menerapkan ke ComponentGuaranteesAttribute rakitan, jenis, atau anggota jenis. Aplikasinya bersifat hierarkis. Artinya, secara default, jaminan yang ditentukan oleh Guarantees properti atribut pada tingkat perakitan mendefinisikan jaminan semua jenis dalam rakitan dan semua anggota dalam jenis tersebut. Demikian pula, jika jaminan diterapkan ke jenis , secara default itu juga berlaku untuk setiap anggota jenis.

Jaminan yang diwariskan ini dapat ditimpa dengan menerapkan ComponentGuaranteesAttribute ke jenis individu dan jenis anggota. Namun, menjamin bahwa mengambil alih default hanya dapat melemahkan jaminan; mereka tidak dapat memperkuatnya. Misalnya, jika rakitan ditandai dengan None jaminan, jenis dan anggotanya tidak memiliki jaminan kompatibilitas, dan jaminan lain yang diterapkan pada jenis atau anggota dalam rakitan diabaikan.

Uji jaminan

Properti Guarantees mengembalikan anggota ComponentGuaranteesOptions enumerasi, yang ditandai dengan FlagsAttribute atribut . Ini berarti Bahwa Anda harus menguji bendera yang Anda minati dengan menutupi bendera yang berpotensi tidak diketahui. Misalnya, contoh berikut menguji apakah jenis ditandai sebagai Stable.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee);

' Test whether guarantee is Stable.
If (guarantee And ComponentGuaranteesOptions.Stable) = ComponentGuaranteesOptions.Stable Then
   Console.WriteLine("{0} is marked as {1}.", typ.Name, guarantee)
End If

Contoh berikut menguji apakah jenis ditandai sebagai Stable atau Exchange.

// Test whether guarantee is Stable or Exchange.
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) > 0)
   Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee);

' Test whether guarantee is Stable or Exchange.
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) > 0 Then
   Console.WriteLine("{0} is marked as Stable or Exchange.", typ.Name, guarantee)
End If

Contoh berikut menguji dengan lebih banyak jenis ditandai sebagai None (yaitu, tidak juga Stable Exchange).

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee);

' Test whether there is no guarantee (neither Stable nor Exchange).
If (guarantee And (ComponentGuaranteesOptions.Stable Or ComponentGuaranteesOptions.Exchange)) = 0 Then
   Console.WriteLine("{0} has no compatibility guarantee.", typ.Name, guarantee)
End If

Bagikan melalui