Bagikan melalui

Praktik Terbaik: Penerapan Versi Kontrak Data

Topik ini mencantumkan praktik terbaik untuk membuat kontrak data yang dapat berkembang dengan mudah dari waktu ke waktu. Untuk informasi selengkapnya tentang kontrak data, lihat topik dalam Menggunakan Kontrak Data.

Catatan tentang Validasi Skema

Dalam membahas penerapan versi kontrak data, penting untuk dicatat bahwa skema kontrak data yang diekspor oleh Windows Communication Foundation (WCF) tidak memiliki dukungan penerapan versi apa pun, selain fakta bahwa elemen ditandai sebagai opsional secara default.

Ini berarti bahwa bahkan skenario penerapan versi yang paling umum, seperti menambahkan anggota data baru, tidak dapat diimplementasikan dengan cara yang mulus sehubungan dengan skema tertentu. Versi kontrak data yang lebih baru (dengan anggota data baru, misalnya) tidak memvalidasi menggunakan skema lama.

Namun, ada banyak skenario di mana kepatuhan skema yang ketat tidak diperlukan. Banyak platform layanan Web, termasuk layanan Web WCF dan XML yang dibuat menggunakan ASP.NET, tidak melakukan validasi skema secara default dan karenanya mentolerir elemen tambahan yang tidak dijelaskan oleh skema. Saat bekerja dengan platform tersebut, banyak skenario penerapan versi lebih mudah diterapkan.

Dengan demikian, ada dua set pedoman penerapan versi kontrak data: satu set untuk skenario di mana validitas skema yang ketat penting, dan satu set lain untuk skenario ketika tidak.

Penerapan versi saat validasi skema diperlukan

Jika validitas skema yang ketat diperlukan di semua arah (baru-ke-lama dan lama-ke-baru), kontrak data harus dianggap tidak dapat diubah. Jika penerapan versi diperlukan, kontrak data baru harus dibuat, dengan nama atau namespace layanan yang berbeda, dan kontrak layanan menggunakan jenis data harus diberi versi yang sesuai.

Misalnya, kontrak layanan pemrosesan pesanan pembelian bernama PoProcessing dengan operasi PostPurchaseOrder mengambil parameter yang sesuai dengan PurchaseOrder kontrak data. PurchaseOrder Jika kontrak harus berubah, Anda harus membuat kontrak data baru, yaitu , PurchaseOrder2yang mencakup perubahan. Anda kemudian harus menangani penerapan versi di tingkat kontrak layanan. Misalnya, dengan membuat operasi PostPurchaseOrder2 yang menggunakan parameter PurchaseOrder2, atau dengan membuat kontrak layanan PoProcessing2 di mana operasi PostPurchaseOrder menggunakan kontrak data PurchaseOrder2.

Perhatikan bahwa perubahan dalam kontrak data yang dirujuk oleh kontrak data lain juga diperluas ke lapisan model layanan. Misalnya, dalam skenario PurchaseOrder sebelumnya kontrak data tidak perlu berubah. Namun, ini berisi anggota data dari Customer kontrak data, yang pada gilirannya berisi anggota data dari kontrak data Address, yang memang perlu diubah. Dalam hal ini, Anda harus membuat Address2 kontrak data dengan perubahan yang diperlukan, Customer2 kontrak data yang berisi Address2 anggota data, dan PurchaseOrder2 kontrak data yang berisi Customer2 anggota data. Seperti dalam kasus sebelumnya, kontrak layanan juga harus diberi versi.

Meskipun dalam contoh ini nama diubah (dengan menambahkan "2"), rekomendasinya adalah mengubah namespace alih-alih nama dengan menambahkan namespace baru dengan nomor versi atau tanggal. Misalnya, http://schemas.contoso.com/2005/05/21/PurchaseOrder kontrak data akan berubah menjadi http://schemas.contoso.com/2005/10/14/PurchaseOrder kontrak data.

Untuk informasi selengkapnya, lihat Praktik Terbaik: Penerapan Versi Layanan.

Terkadang, Anda harus menjamin kepatuhan skema yang ketat untuk pesan yang dikirim oleh aplikasi Anda, tetapi tidak dapat mengandalkan pesan masuk agar mematuhi skema secara ketat. Dalam hal ini, ada bahaya bahwa pesan masuk mungkin berisi data asing. Nilai berlebihan disimpan dan dikembalikan oleh WCF sehingga pesan skema tidak valid dikirim. Untuk menghindari masalah ini, fitur round-tripping harus dinonaktifkan. Ada dua cara untuk melakukan ini.

Untuk informasi lebih lanjut tentang round-tripping, lihat Forward-Compatible Kontrak Data.

Penerapan versi saat validasi skema tidak diperlukan

Kepatuhan skema yang ketat jarang diperlukan. Banyak platform mentolerir elemen tambahan yang tidak dijelaskan oleh skema. Selama ini ditoleransi, serangkaian fitur lengkap yang dijelaskan dalam Penerapan Versi Kontrak Data dan Kontrak DataForward-Compatible dapat digunakan. Panduan berikut direkomendasikan.

Beberapa panduan harus diikuti dengan tepat agar dapat mengirim versi baru ketika yang lama diharapkan atau mengirim versi lama ketika yang baru diharapkan. Pedoman lain tidak benar-benar diperlukan, tetapi tercantum di sini karena mungkin terpengaruh oleh masa depan penerapan versi skema.

  1. Jangan mencoba membuat versi kontrak data berdasarkan jenis pewarisan. Untuk membuat versi yang lebih baru, ubah kontrak data pada jenis yang sudah ada atau buat jenis baru yang tidak terkait.

  2. Penggunaan pewarisan bersama dengan kontrak data diizinkan, asalkan warisan tidak digunakan sebagai mekanisme penerapan versi dan bahwa aturan tertentu diikuti. Jika jenis berasal dari jenis dasar tertentu, jangan membuatnya berasal dari jenis dasar yang berbeda dalam versi mendatang (kecuali memiliki kontrak data yang sama). Ada satu pengecualian untuk ini: Anda dapat menyisipkan jenis ke dalam hierarki antara jenis kontrak data dan jenis dasarnya, tetapi hanya jika tidak berisi anggota data dengan nama yang sama dengan anggota lain dalam versi yang mungkin dari jenis lain dalam hierarki. Secara umum, menggunakan anggota data dengan nama yang sama pada tingkat yang berbeda dari hierarki warisan yang sama dapat menyebabkan masalah penerapan versi yang serius dan harus dihindari.

  3. Dimulai dengan versi pertama kontrak data, selalu terapkan IExtensibleDataObject untuk mengaktifkan round-tripping (proses mengirim dan menerima kembali data tanpa perubahan). Untuk informasi selengkapnya, lihat Kontrak DataForward-Compatible. Jika Anda telah merilis satu atau beberapa versi jenis tanpa menerapkan antarmuka ini, terapkan di versi jenis berikutnya.

  4. Di versi yang lebih baru, jangan ubah nama kontrak data atau namespace layanan. Jika mengubah nama atau ruang nama jenis yang mendasari kontrak data, pastikan untuk mempertahankan nama kontrak data dan ruang nama dengan menggunakan mekanisme yang sesuai, seperti properti Name dari DataContractAttribute. Untuk informasi selengkapnya tentang penamaan, lihat Nama Kontrak Data.

  5. Di versi yang lebih baru, jangan ubah nama anggota data apa pun. Jika mengubah nama bidang, properti, atau peristiwa yang mendasari anggota data, gunakan Name properti DataMemberAttribute untuk mempertahankan nama anggota data yang ada.

  6. Di versi-versi yang lebih baru, jangan ubah tipe dari setiap bidang, properti, atau acara yang menjadi bagian dari anggota data, sehingga kontrak data yang dihasilkan untuk anggota data tersebut tidak berubah. Perlu diingat bahwa jenis antarmuka setara dengan Object untuk tujuan menentukan kontrak data yang diharapkan.

  7. Di versi yang lebih baru, jangan ubah urutan anggota data yang ada dengan menyesuaikan properti dari atribut Order.

  8. Di versi yang lebih baru, anggota data baru dapat ditambahkan. Mereka harus selalu mengikuti aturan ini:

    1. Properti IsRequired harus selalu dibiarkan pada nilai defaultnya.false

    2. Jika nilai null default atau nol untuk anggota tidak dapat diterima, metode panggilan balik harus disediakan menggunakan OnDeserializingAttribute untuk memberikan default yang wajar jika anggota tidak ada di aliran masuk. Untuk informasi selengkapnya tentang panggilan balik, lihat panggilan balik SerialisasiVersion-Tolerant.

    3. Properti DataMemberAttribute.Order harus digunakan untuk memastikan bahwa semua anggota data yang baru ditambahkan muncul setelah anggota data yang ada. Cara yang disarankan untuk melakukan ini adalah sebagai berikut: Tidak ada anggota data dalam versi pertama kontrak data yang harus memiliki kumpulan properti mereka Order . Semua anggota data yang ditambahkan dalam versi 2 kontrak data harus mengatur properti mereka Order ke 2. Semua anggota data yang ditambahkan dalam versi 3 dari kontrak data seharusnya disetel Order ke 3, dan seterusnya. Diperbolehkan memiliki lebih dari satu anggota data dengan nomor yang sama Order.

  9. Jangan hapus anggota data di versi yang lebih baru, bahkan jika IsRequired tetap pada properti bawaannya false di versi sebelumnya.

  10. Jangan ubah IsRequired properti pada anggota data yang ada dari versi ke versi.

  11. Untuk anggota data yang wajib (di mana IsRequired adalah true), jangan ubah properti EmitDefaultValue dari satu versi ke versi lainnya.

  12. Jangan mencoba membuat hierarki penerapan versi bercabang. Artinya, harus selalu ada jalur dalam setidaknya satu arah dari versi apa pun ke versi lain hanya menggunakan perubahan yang diizinkan oleh pedoman ini.

    Misalnya, jika versi 1 dari kontrak data Orang hanya berisi anggota data Nama, Anda tidak boleh membuat versi 2a dari kontrak yang hanya menambahkan anggota Usia dan versi 2b yang hanya menambahkan anggota Alamat. Dari 2a ke 2b akan melibatkan penghapusan Usia dan menambahkan Alamat; pergi ke arah lain akan memerlukan penghapusan Alamat dan menambahkan Usia. Menghapus anggota tidak diizinkan oleh pedoman ini.

  13. Anda umumnya tidak boleh membuat subjenis baru dari jenis kontrak data yang ada dalam versi baru aplikasi Anda. Demikian juga, Anda tidak boleh membuat kontrak data baru yang digunakan sebagai pengganti anggota data yang dinyatakan sebagai Objek atau sebagai jenis antarmuka. Membuat kelas baru ini hanya diizinkan ketika Anda tahu bahwa Anda dapat menambahkan jenis baru ke daftar jenis yang diketahui dari semua instans aplikasi lama Anda. Misalnya, di versi 1 aplikasi Anda, Anda mungkin memiliki jenis kontrak data LibraryItem dengan subjenis kontrak data Buku dan Koran. LibraryItem kemudian akan memiliki daftar jenis yang diketahui yang berisi Buku dan Koran. Misalkan Anda sekarang menambahkan jenis Majalah di versi 2 yang merupakan subjenis LibraryItem. Jika Anda mengirim instans Magazine dari versi 2 ke versi 1, kontrak data Magazine tidak ditemukan dalam daftar tipe terkenal dan terjadi pengecualian.

  14. Anda tidak boleh menambahkan atau menghapus anggota enumerasi antar versi. Anda juga tidak boleh mengganti nama anggota enumerasi, kecuali Anda menggunakan properti Nama pada EnumMemberAttribute atribut untuk menjaga nama mereka dalam model kontrak data tetap sama.

  15. Koleksi dapat dipertukarkan dalam model kontrak data seperti yang dijelaskan dalam Jenis Koleksi dalam Kontrak Data. Ini memungkinkan tingkat fleksibilitas yang besar. Namun, pastikan Anda tidak secara tidak sengaja mengubah jenis koleksi dengan cara yang tidak dapat dipertukarkan dari versi ke versi. Misalnya, jangan ubah dari koleksi yang tidak disesuaikan (yaitu, tanpa CollectionDataContractAttribute atribut) menjadi koleksi yang disesuaikan atau koleksi yang disesuaikan menjadi yang tidak disesuaikan. Selain itu, jangan ubah properti pada CollectionDataContractAttribute dari versi ke versi. Satu-satunya perubahan yang diizinkan adalah menambahkan properti Nama atau Namespace jika nama atau namespace layanan jenis koleksi yang mendasar telah berubah dan Anda perlu membuat nama kontrak data dan namespace layanannya sama seperti di versi sebelumnya.

Beberapa panduan yang tercantum di sini dapat diabaikan dengan aman ketika keadaan khusus berlaku. Pastikan Anda sepenuhnya memahami mekanisme serialisasi, deserialisasi, dan skema yang terlibat sebelum menyimpang dari pedoman.

Lihat juga

  • Last updated on