En İyi Uygulamalar: Veri Sözleşmesi Sürümü Oluşturma

  • Makale

Bu konuda, zaman içinde kolayca geliştirilebilen veri sözleşmeleri oluşturmaya yönelik en iyi yöntemler listelanmaktadır. Veri sözleşmeleri hakkında daha fazla bilgi için Veri Sözleşmelerini Kullanma başlığına bakın.

Şema Doğrulama ile ilgili not

Veri sözleşmesi sürüm oluşturmanın tartışılmasında, Windows Communication Foundation (WCF) tarafından dışarı aktarılan veri sözleşmesi şemasının, öğelerin varsayılan olarak isteğe bağlı olarak işaretlenmesi dışında herhangi bir sürüm oluşturma desteğine sahip olmadığını unutmayın.

Bu, yeni veri üyesi ekleme gibi en yaygın sürüm oluşturma senaryolarının bile belirli bir şemayla ilgili olarak sorunsuz bir şekilde uygulanamayacağı anlamına gelir. Veri sözleşmesinin daha yeni sürümleri (örneğin, yeni bir veri üyesiyle) eski şemayı kullanarak doğrulamaz.

Ancak, katı şema uyumluluğu gerekmediği birçok senaryo vardır. ASP.NET kullanılarak oluşturulan WCF ve XML Web hizmetleri de dahil olmak üzere birçok Web hizmeti platformu varsayılan olarak şema doğrulaması gerçekleştirmez ve bu nedenle şema tarafından açıklanmayan ek öğeleri tolere eder. Bu tür platformlarla çalışırken, birçok sürüm oluşturma senaryosu daha kolaydır.

Bu nedenle, iki veri sözleşmesi sürüm oluşturma kılavuzu kümesi vardır: katı şema geçerliliğinin önemli olduğu senaryolar için bir küme ve olmadığı durumlarda senaryolar için başka bir küme.

Şema Doğrulaması Gerektiğinde Sürüm Oluşturma

Tüm yönlerde (yeniden eskiye ve eskiden yeniye) katı şema geçerliliği gerekiyorsa, veri sözleşmeleri sabit kabul edilmelidir. Sürüm oluşturma gerekiyorsa, farklı bir ada veya ad alanına sahip yeni bir veri sözleşmesi oluşturulmalıdır ve veri türünü kullanan hizmet sözleşmesi uygun şekilde sürümlenmelidir.

Örneğin, bir işlemle PostPurchaseOrder adlandırılan PoProcessing bir satın alma siparişi işleme hizmet sözleşmesi, veri sözleşmesine uygun bir PurchaseOrder parametre alır. Sözleşmenin değişmesi PurchaseOrder gerekiyorsa, değişiklikleri içeren yeni bir veri sözleşmesi PurchaseOrder2oluşturmanız gerekir. Ardından sürüm oluşturma işlemini hizmet sözleşmesi düzeyinde işlemeniz gerekir. Örneğin, parametresini PurchaseOrder2 alan bir PostPurchaseOrder2 işlem oluşturarak veya işlemin bir veri sözleşmesi aldığı PostPurchaseOrder bir PoProcessing2PurchaseOrder2 hizmet sözleşmesi oluşturarak.

Diğer veri sözleşmeleri tarafından başvuruda bulunan veri sözleşmelerindeki değişikliklerin de hizmet modeli katmanına genişletildiğini unutmayın. Örneğin, önceki senaryoda veri sözleşmesinin PurchaseOrder değişmesi gerekmez. Ancak, bir veri sözleşmesinin Customer veri üyesini içerir ve bu da veri sözleşmesinin Address değiştirilmesi gereken bir veri üyesini içerir. Bu durumda, gerekli değişikliklerle bir Address2 veri sözleşmesi, veri üyesini içeren Address2 bir Customer2 veri sözleşmesi ve veri üyesi içeren bir PurchaseOrder2Customer2 veri sözleşmesi oluşturmanız gerekir. Önceki örnekte olduğu gibi hizmet sözleşmesinin de sürümüne sahip olması gerekir.

Bu örneklerde adlar değiştiriliyor olsa da (bir "2" eklenerek), bir sürüm numarası veya tarih içeren yeni ad alanları ekleyerek ad alanlarının yerine ad alanlarının değiştirilmesi önerilmektedir. Örneğin, http://schemas.contoso.com/2005/05/21/PurchaseOrder veri sözleşmesi veri sözleşmesi olarak http://schemas.contoso.com/2005/10/14/PurchaseOrder değişir.

Daha fazla bilgi için bkz. En İyi Yöntemler: Hizmet Sürümü Oluşturma.

Bazen, uygulamanız tarafından gönderilen iletiler için sıkı şema uyumluluğunu garanti etmeniz gerekir, ancak gelen iletilerin kesinlikle şema uyumlu olmasını sağlayamazsınız. Bu durumda, gelen bir iletinin gereksiz veriler içermesi tehlikesi vardır. Fazlalık değerler WCF tarafından depolanır ve döndürülür ve bu nedenle şema geçersiz iletilerin gönderilmesiyle sonuçlanır. Bu sorunu önlemek için yuvarlama özelliği kapatılmalıdır. Bunu yapmanın iki yolu vardır.

Yuvarlama hakkında daha fazla bilgi için bkz . İletme Uyumlu Veri Sözleşmeleri.

Şema Doğrulaması Gerekli Olmadığında Sürüm Oluşturma

Sıkı şema uyumluluğu nadiren gereklidir. Birçok platform, şema tarafından açıklanmayan ek öğeleri tolere eder. Bu durum tolere edilebildiği sürece, Veri Sözleşmesi Sürüm Oluşturma ve İleTme Uyumlu Veri Sözleşmeleri'nde açıklanan özelliklerin tamamı kullanılabilir. Aşağıdaki yönergeler önerilir.

Daha eski bir sürümün beklendiği bir türün yeni sürümlerini göndermek veya yeni sürümün beklendiği eski bir sürümü göndermek için yönergelerin tam olarak izlenmesi gerekir. Diğer yönergeler kesinlikle gerekli değildir, ancak şema sürümü oluşturmanın geleceğinden etkilenebileceği için burada listelenmiştir.

  1. Tür devralma yoluyla veri sözleşmelerini sürüme eklemeye kalkışmayın. Sonraki sürümleri oluşturmak için, var olan bir türdeki veri sözleşmesini değiştirin veya yeni bir ilişkisiz tür oluşturun.

  2. Devralma işleminin sürüm oluşturma mekanizması olarak kullanılmaması ve belirli kurallara uyulması koşuluyla, devralma işleminin veri sözleşmeleriyle birlikte kullanılmasına izin verilir. Bir tür belirli bir temel türden türetilirse, gelecekteki bir sürümde (aynı veri sözleşmesine sahip olmadığı sürece) farklı bir taban türünden türetilmiş olmasını sağlamayın. Bunun bir özel durumu vardır: Hiyerarşiye bir veri sözleşmesi türü ile temel türü arasında bir tür ekleyebilirsiniz, ancak yalnızca hiyerarşideki diğer türlerin olası sürümlerindeki diğer üyelerle aynı adlara sahip veri üyeleri içermiyorsa. Genel olarak, aynı devralma hiyerarşisinin farklı düzeylerinde aynı adlara sahip veri üyelerini kullanmak ciddi sürüm oluşturma sorunlarına yol açabilir ve bundan kaçınılmalıdır.

  3. Veri sözleşmesinin ilk sürümünden başlayarak, her zaman yuvarlak kopyalamayı etkinleştirmek için uygulayın IExtensibleDataObject . Daha fazla bilgi için bkz . İletme Uyumlu Veri Sözleşmeleri. Bir türün bir veya daha fazla sürümünü bu arabirimi uygulamadan yayımladıysanız, türün sonraki sürümünde uygulayın.

  4. Sonraki sürümlerde, veri sözleşmesi adını veya ad alanını değiştirmeyin. Veri sözleşmesinin temelini oluşturan türün adını veya ad alanını değiştiriyorsanız, özelliği gibi Name uygun mekanizmaları kullanarak veri sözleşmesi adını ve ad alanını koruduğundan DataContractAttributeemin olun. Adlandırma hakkında daha fazla bilgi için bkz . Veri Sözleşmesi Adları.

  5. Sonraki sürümlerde hiçbir veri üyesinin adını değiştirmeyin. Veri üyesinin temelini oluşturan alanın, özelliğin veya olayın adını değiştiriyorsanız, mevcut veri üyesi adını korumak için öğesinin özelliğini DataMemberAttribute kullanınName.

  6. Sonraki sürümlerde, bir veri üyesinin temelini oluşturan hiçbir alanın, özelliğin veya olayın türünü değiştirmeyin; böylece bu veri üyesi için sonuçta elde edilen veri sözleşmesi değişir. Beklenen veri sözleşmesini belirleme amacıyla arabirim türlerinin ile eşdeğer Object olduğunu unutmayın.

  7. Sonraki sürümlerde, özniteliğinin özelliğini ayarlayarak Order mevcut veri üyelerinin sırasını değiştirmeyin DataMemberAttribute .

  8. Sonraki sürümlerde yeni veri üyeleri eklenebilir. Her zaman şu kurallara uymalıdır:

    1. IsRequired özelliği her zaman varsayılan değerinde falsebırakılmalıdır.

    2. Üye için varsayılan veya sıfır değeri null kabul edilemezse, üyenin gelen akışta mevcut olmaması durumunda makul bir varsayılan değer sağlamak için kullanılarak OnDeserializingAttribute bir geri çağırma yöntemi sağlanmalıdır. Geri çağırma hakkında daha fazla bilgi için bkz . Sürüme Dayanıklı Serileştirme Geri Çağırmaları.

    3. özelliği, DataMemberAttribute.Order yeni eklenen tüm veri üyelerinin mevcut veri üyelerinden sonra göründüğünden emin olmak için kullanılmalıdır. Bunu yapmanın önerilen yolu şu şekildedir: Veri sözleşmesinin ilk sürümündeki veri üyelerinden hiçbirinin özellik kümesi olmamalıdır Order . Veri sözleşmesinin 2. sürümünde eklenen tüm veri üyelerinin özellikleri 2 olarak ayarlanmalıdır Order . Veri sözleşmesinin 3. sürümünde eklenen tüm veri üyelerinin 3 olarak ayarlanmış olması gerekir Order . Birden fazla veri üyesinin aynı Order sayıya ayarlanmasına izin verilebilir.

  9. Özellik önceki sürümlerde varsayılan özelliğinde bırakılsa IsRequired bile sonraki sürümlerdeki veri üyelerini false kaldırmayın.

  10. Mevcut veri üyelerindeki IsRequired özelliği sürümden sürüme değiştirmeyin.

  11. Gerekli veri üyeleri için (burada IsRequired ), trueözelliği sürümden sürüme değiştirmeyin EmitDefaultValue .

  12. Dallanmış sürüm oluşturma hiyerarşileri oluşturmayı denemeyin. Başka bir deyişle, yalnızca bu yönergelerin izin verdiği değişiklikleri kullanarak her zaman herhangi bir sürümden başka bir sürüme en az bir yönde bir yol olmalıdır.

    Örneğin, bir Kişi veri sözleşmesinin sürüm 1'i yalnızca Ad veri üyesini içeriyorsa, sözleşmenin yalnızca Yaş üyesini ve yalnızca Adres üyesini ekleyen sürüm 2b'yi eklememelisiniz. 2a'dan 2b'ye geçmek için Yaş'ın kaldırılması ve Adres eklenmesi gerekeceğinden; Diğer yöne gitmek için Adres'in kaldırılması ve Yaş eklenmesi gerekir. Üyelerin kaldırılmasına bu yönergeler tarafından izin verilmez.

  13. Genellikle uygulamanızın yeni bir sürümünde mevcut veri sözleşmesi türlerinin yeni alt türlerini oluşturmamalısınız. Benzer şekilde, Nesne olarak veya arabirim türleri olarak bildirilen veri üyeleri yerine kullanılan yeni veri sözleşmeleri oluşturmamalısınız. Bu yeni sınıfların oluşturulmasına yalnızca yeni türleri eski uygulamanızın tüm örneklerinin bilinen türler listesine ekleyebileceğinizi bildiğiniz durumlarda izin verilir. Örneğin, uygulamanızın 1. sürümünde Kitap ve Gazete veri sözleşmesi alt türlerine sahip LibraryItem veri sözleşmesi türüne sahip olabilirsiniz. LibraryItem daha sonra Kitap ve Gazete içeren bilinen bir tür listesine sahip olur. Şimdi LibraryItem'in alt türü olan sürüm 2'de bir Dergi türü eklediğinizi varsayalım. Sürüm 2'den sürüm 1'e bir Magazine örneği gönderirseniz, Magazine veri sözleşmesi bilinen türler listesinde bulunmaz ve bir özel durum oluşturulur.

  14. Sürümler arasında numaralandırma üyeleri eklememeli veya kaldırmamalısınız. Ayrıca, adlarını veri sözleşmesi modelinde aynı tutmak için öznitelikteki EnumMemberAttribute Name özelliğini kullanmadığınız sürece numaralandırma üyelerini yeniden adlandırmamalısınız.

  15. Koleksiyonlar, Veri Sözleşmelerindeki Koleksiyon Türleri bölümünde açıklandığı gibi veri sözleşmesi modelinde değiştirilebilir. Bu, büyük ölçüde esneklik sağlar. Ancak, koleksiyon türünü yanlışlıkla sürümden sürüme değiştirilemeyen bir şekilde değiştirmediğinizden emin olun. Örneğin, özelleştirilmemiş bir koleksiyondan (öznitelik olmadan CollectionDataContractAttribute ) özelleştirilmiş koleksiyona veya özelleştirilmiş koleksiyona, özelleştirilmemiş koleksiyona değiştirmeyin. Ayrıca, sürümündeki özellikleri sürümden sürüme değiştirmeyin CollectionDataContractAttribute . Temel koleksiyon türünün adı veya ad alanı değiştiyse ve veri sözleşmesi adını ve ad alanını önceki sürümdekiyle aynı yapmanız gerekiyorsa, izin verilen tek değişiklik Bir Ad veya Ad Alanı özelliği eklemektir.

Burada listelenen bazı yönergeler, özel koşullar uygulandığında güvenle yoksayılabilir. Yönergelerden sapmadan önce serileştirme, seri durumdan çıkarma ve şema mekanizmalarını tam olarak anladığınızdan emin olun.

Ayrıca bkz.