Kelas System.Runtime.Versioning.ComponentGuaranteesAttribute

Nota

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

ComponentGuaranteesAttribute digunakan oleh pengembang komponen dan pustaka kelas untuk menunjukkan tingkat kompatibilitas yang dapat diharapkan oleh pengguna pustaka tersebut di berbagai 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.

Nota

Runtime bahasa umum (Common Language Runtime, CLR) tidak menggunakan atribut ini dengan cara apapun. 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

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

• 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 antar versi secara 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 besar dibuat, versi lama tidak dimodifikasi tetapi ada bersama versi baru. Pelaksanaan berdampingan adalah cara yang diharapkan untuk membuat klien yang ada berfungsi saat perubahan yang mengganggu kompatibilitas dilakukan. Untuk informasi lebih lanjut, lihat bagian tentang kompatibilitas sejajar yang akan dibahas nanti dalam 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 bisa menggunakan eksekusi paralel untuk memperbaiki masalah. Untuk informasi selengkapnya, lihat bagian kompatibilitas stabil.

• Kompatibilitas versi ke versi Exchange (ComponentGuaranteesOptions.Exchange). Usaha luar biasa dilakukan untuk memastikan bahwa versi di masa mendatang tidak akan mengacaukan 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 menjamin 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 berfungsi ketika lebih dari satu versi rakitan dimuat ke dalam domain aplikasi yang sama. Perubahan mendasar diperbolehkan selama dilakukan pada rakitan yang memiliki nomor versi 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 SideBySide dengan memodifikasi versi lama secara destruktif.

Kompatibilitas yang stabil

Menandai jenis sebagai ComponentGuaranteesOptions.Stable menunjukkan bahwa jenisnya harus tetap stabil di seluruh versi. Namun, mungkin juga dimungkinkan untuk versi sampingan dari tipe stabil untuk ada dalam domain aplikasi yang sama.

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

• Menambahkan bidang instans privat ke tipe, atau menghapus bidang dari tipe, 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, maka dapat ditingkatkan ke Exchange. Namun, 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. Tipe-tipe ini dimaksudkan untuk digunakan dalam pertukaran antara komponen yang dibangun secara independen di antara semua batas komponen dalam hal waktu (versi apa pun dari CLR atau versi apa pun dari komponen atau aplikasi) dan ruang (lintas proses, lintas CLR dalam satu proses, domain aplikasi lintas satu CLR). Jika perubahan yang merusak dilakukan pada tipe pertukaran, tidak mungkin memperbaiki masalah dengan memuat beberapa versi tipe tersebut.

Tipe pertukaran sebaiknya diubah hanya ketika masalah sangat serius (misalnya, masalah keamanan yang serius) atau kemungkinan terjadinya kerusakan sangat kecil (artinya, jika perilaku sudah rusak dengan cara yang acak sehingga kode tersebut tidak mungkin bergantung padanya). 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. Diperlukan serialisasi yang toleran terhadap versi.

• Menambahkan atau menghapus bidang instans privat. Risiko ini mengubah format serialisasi tipe dan merusak kode klien yang menggunakan refleksi.

• Mengubah serialisabilitas tipe. Jenis yang tidak dapat diserialisasikan mungkin tidak dapat diserialisasikan, dan sebaliknya.

• Melemparkan pengecualian yang berbeda dalam metode.

• Mengubah rentang nilai pengembalian metode, kecuali jika definisi anggota memungkinkan hal ini dan dengan jelas menunjukkan bagaimana klien harus menangani nilai yang tidak diketahui.

• Memperbaiki sebagian besar bug. Konsumen tipe ini akan mengandalkan perilaku yang ada.

Setelah komponen, jenis, atau anggota ditandai dengan jaminan Exchange, 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 kompatibilitas Exchange. Selain itu, jenis pertukaran tidak dapat bergantung pada perilaku API Windows yang rentan berubah.

Garansi Komponen

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

Karakteristik komponen	Pertukaran	Stabil	Berlampingan	Tidak
Dapat digunakan dalam antarmuka antara komponen yang versinya secara independen.	Ya	N	N	N
Dapat digunakan (secara pribadi) oleh rakitan yang memiliki versinya sendiri.	Ya	Ya	Ya	N
Dapat memiliki beberapa versi dalam satu domain aplikasi.	N	Ya	Ya	Ya
Dapat membuat perubahan yang memutus kompatibilitas	N	N	Ya	Ya
Diuji untuk memastikan bahwa beberapa versi assembly dapat dimuat bersama-sama.	N	N	Ya	N
Dapat membuat perubahan penting dalam konteks.	N	N	N	Ya
Dapat membuat perubahan layanan yang tidak mengganggu dan sangat aman di tempat.	Ya	Ya	Ya	Ya

Terapkan atribut

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

Jaminan yang diwariskan ini dapat diubah dengan menerapkan ComponentGuaranteesAttribute ke tipe individu dan anggota tipe. Namun, jaminan yang mengecualikan pengaturan default hanya dapat melemahkan jaminannya; mereka tidak dapat memperkuatnya. Misalnya, jika rakitan ditandai dengan jaminan None, 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 enumerasi ComponentGuaranteesOptions, yang ditandai dengan atribut FlagsAttribute. Ini berarti bahwa Anda harus menguji penanda yang Anda minati dengan memblokir penanda yang mungkin tidak diketahui. Misalnya, contoh berikut menguji apakah jenis ditandai sebagai Stable.

// Test whether guarantee is Stable.
if ((guarantee & ComponentGuaranteesOptions.Stable) == ComponentGuaranteesOptions.Stable)
   Console.WriteLine($"{typ.Name} is marked as {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($"{typ.Name} is marked as Stable or Exchange.");

' 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 apakah jenis ditandai sebagai None (yaitu, tidak juga StableExchange).

// Test whether there is no guarantee (neither Stable nor Exchange).
if ((guarantee & (ComponentGuaranteesOptions.Stable | ComponentGuaranteesOptions.Exchange)) == 0)
   Console.WriteLine($"{typ.Name} has no compatibility 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