Veri Sözleşmesi Sürümü Oluşturma

Uygulamalar geliştikçe, hizmetlerin kullandığı veri sözleşmelerini de değiştirmeniz gerekebilir. Bu konuda, veri sözleşmelerinin nasıl sürümlendiği açıklanmaktadır. Bu konu başlığında, veri sözleşmesi sürüm oluşturma mekanizmaları açıklanmaktadır. Tam bir genel bakış ve açıklayıcı sürüm oluşturma kılavuzu için bkz . En İyi Yöntemler: Veri Sözleşmesi Sürüm Oluşturma.

Fonksiyonu Bozan ve Bozmayan Değişiklikler

Veri sözleşmesinde yapılan değişiklikler bozulabilir veya bölünemez. Bir veri sözleşmesi bölünemez bir şekilde değiştirildiğinde, sözleşmenin eski sürümünü kullanan bir uygulama daha yeni sürümü kullanarak bir uygulamayla iletişim kurabilir ve sözleşmenin daha yeni sürümünü kullanan bir uygulama eski sürümü kullanarak bir uygulamayla iletişim kurabilir. Öte yandan, mevcut işlevselliği bozan bir değişiklik, bir veya her iki yönde iletişimi engeller.

Bir türe yapılan ve iletim ve alınma şeklini nasıl etkilediğini değiştirmeyen değişiklikler kesintiye uğramaz. Bu tür değişiklikler veri sözleşmesini değiştirmez, yalnızca temel alınan türü değiştirir. Örneğin, Name'i DataMemberAttribute özelliğini eski sürüm adına ayarlarsanız, bir alanın adını sorunsuz bir şekilde değiştirebilirsiniz. Aşağıdaki kod, bir veri sözleşmesinin 1. sürümünü gösterir.

// Version 1
[DataContract]
public class Person
{
    [DataMember]
    private string Phone;
}

' Version 1
<DataContract()> _
Public Class Person
    <DataMember()> _
    Private Phone As String
End Class

Aşağıdaki kodda bölünemez bir değişiklik gösterilmektedir.

// Version 2. This is a non-breaking change because the data contract
// has not changed, even though the type has.
[DataContract]
public class Person
{
    [DataMember(Name = "Phone")]
    private string Telephone;
}

' Version 2. This is a non-breaking change because the data contract 
' has not changed, even though the type has.
<DataContract()> _
Public Class Person
    <DataMember(Name:="Phone")> _
    Private Telephone As String
End Class

Bazı değişiklikler iletilen verileri değiştirir, ancak hataya neden olabilir veya olmayabilir. Aşağıdaki değişiklikler her zaman kesintiye neden olur:

Veri sözleşmesinin Name veya Namespace değerini değiştirme.
Order özelliğini kullanarak DataMemberAttribute veri üyelerinin sırasını değiştirme.
Veri üyesini yeniden adlandırma.
Veri üyesinin veri sözleşmesini değiştirme. Örneğin, veri üyesinin türünü bir tamsayıdan dizeye veya "Müşteri" adlı veri sözleşmesine sahip bir türden "Person" adlı veri sözleşmesine sahip bir türe değiştirme.

Aşağıdaki değişiklikler de mümkündür.

Veri Üyeleri Ekleme ve Kaldırma

Çoğu durumda, veri üyesi eklemek veya kaldırmak, eski şemaya karşı yeni örneklerin doğrulanması gibi katı şema geçerliliği gerektirmediğiniz sürece, çok önemli bir değişiklik olarak kabul edilmez.

Ek alanı olan bir tür, eksik alanı olan bir türe seri durumda serideserilize edildiğinde, ek bilgiler göz ardı edilir. (Veri döngüsü amacıyla da depolanabilir; daha fazla bilgi için bkz. Forward-Compatible Veri Sözleşmeleri).

Alanı eksik olan bir tür, ek alanı olan bir türe seri durumdan çıkarıldığında, ek alan varsayılan değerinde (genellikle sıfır veya null) bırakılır. (Varsayılan değer değiştirilebilir; daha fazla bilgi için bkz. Version-Tolerant Serileştirme Geri Çağırmaları.)

Örneğin, CarV1 sınıfını bir istemcide ve CarV2 sınıfını bir hizmette, veya CarV1 sınıfını bir hizmette ve CarV2 sınıfını bir istemcide kullanabilirsiniz.

// Version 1 of a data contract, on machine V1.
[DataContract(Name = "Car")]
public class CarV1
{
    [DataMember]
    private string Model;
}

// Version 2 of the same data contract, on machine V2.
[DataContract(Name = "Car")]
public class CarV2
{
    [DataMember]
    private string Model;

    [DataMember]
    private int HorsePower;
}

' Version 1 of a data contract, on machine V1.
<DataContract(Name:="Car")> _
Public Class CarV1
    <DataMember()> _
    Private Model As String
End Class

' Version 2 of the same data contract, on machine V2.
<DataContract(Name:="Car")> _
Public Class CarV2
    <DataMember()> _
    Private Model As String

    <DataMember()> _
    Private HorsePower As Integer
End Class

Sürüm 2 uç noktası, sürüm 1 uç noktasına başarıyla veri gönderebilir. Veri sözleşmesinin Car 2. sürümünü seri hale getirmek, aşağıdakine benzer şekilde XML verir.

<Car>  
    <Model>Porsche</Model>  
    <HorsePower>300</HorsePower>  
</Car>

V1'deki serileştirme motoru, HorsePower alanı için eşleşen bir veri üyesi bulamaz, bu nedenle veriyi atar.

Ayrıca sürüm 1 uç noktası, sürüm 2 uç noktasına veri gönderebilir. Veri sözleşmesinin Car 1. sürümünü seri hale getirmek, aşağıdakine benzer şekilde XML verir.

<Car>  
    <Model>Porsche</Model>  
</Car>

Sürüm 2 seri durumdan çıkarıcı, gelen XML'de eşleşen veri olmadığından HorsePower alanını ne olarak ayarlayacağını bilmiyor. Bunun yerine, alan varsayılan 0 değerine ayarlanır.

Gerekli Veri Üyeleri

Bir veri üyesi, IsRequired'in DataMemberAttribute özelliği true olarak ayarlanarak gerekli olarak işaretlenebilir. Seri durumdan çıkarılırken gerekli veriler eksikse, veri üyesini varsayılan değerine ayarlamak yerine bir istisna fırlatılır.

Gerekli bir veri üyesi eklemek sistemi bozacak bir değişikliktir. Başka bir deyişle, daha yeni tür yine de eski türe sahip uç noktalara gönderilebilir, ancak tam tersi olmaz. Önceki sürümlerde gerekli olarak işaretlenmiş bir veri üyesinin kaldırılması da önemli bir değişikliktir.

IsRequired özelliği değerini true'den false'ye değiştirmek bozulmaya neden olmaz, ancak false'ten true'e değiştirmek, türün önceki sürümlerinde söz konusu veri üyesi yoksa bozulmaya neden olabilir.

Uyarı

IsRequired özelliği true olarak ayarlanmış olsa da, gelen veriler null veya sıfır olabilir ve bu olasılığı işlemek için bir tür hazırlanmalıdır. Kötü gelen verilere karşı koruma sağlamak için güvenlik mekanizması olarak kullanmayın IsRequired .

Atlanmış Varsayılan Değerler

DataMemberAttribute özniteliğindeki EmitDefaultValue özelliğini false olarak ayarlamak, Veri Üyesi Varsayılan Değerleri'nde açıklandığı gibi mümkündür (önerilmez). Ayar false ise ve varsayılan değerine (genellikle null veya sıfır) ayarlanmışsa, veri üyesi yayımlanmaz. Bu, farklı sürümlerdeki gerekli veri üyeleriyle iki şekilde uyumlu değildir:

Bir sürümde gerekli olan bir veri üyesiyle yapılan veri sözleşmesi, veri üyesinin EmitDefaultValue olarak ayarlandığı falsefarklı bir sürümden varsayılan (null veya sıfır) verileri alamaz.
EmitDefaultValue öğesi false olarak ayarlanmış gerekli bir veri üyesi, varsayılan (null veya sıfır) değeri seri hale getirmek için kullanılamaz, ancak seri durumdan çıkarmada bu tür bir değeri alabilir. Bu, gidip-gelme sorunu yaratır (veriler okunabilir, ancak aynı veriler yazılamaz). Bu nedenle, IsRequiredtrue ve EmitDefaultValuefalse olduğunda, veri sözleşmesinin hiçbir sürümünün gidiş dönüşe neden olmayan bir değer üretemeyeceği şekilde, aynı bileşim diğer tüm sürümler için de geçerli olmalıdır.

Şema ile İlgili Dikkat Edilmesi Gerekenler

Veri sözleşmesi türleri için hangi şemanın üretildiğine ilişkin bir açıklama için bkz. Veri Sözleşmesi Şema Başvurusu.

WCF'nin veri sözleşmesi türleri için ürettiği şema, sürüm oluşturma için hiçbir sağlama yapmaz. Yani, bir türün belirli bir sürümünden dışarı aktarılan şema yalnızca bu sürümde bulunan veri üyelerini içerir. IExtensibleDataObject arabiriminin uygulanması bir türün şemasını değiştirmez.

Veri üyeleri varsayılan olarak isteğe bağlı öğeler olarak şemaya aktarılır. Yani, minOccurs (XML özniteliği) değeri 0 olarak ayarlanır. Gerekli veri üyeleri minOccurs 1 olarak ayarlanmış şekilde dışarı aktarılır.

Şemaya sıkı sıkıya bağlı kalınması gerekiyorsa, bozulmaz olarak kabul edilen değişikliklerin çoğu aslında bozulmalara neden olur. Önceki örnekte, yalnızca CarV1 öğesini içeren bir Model örneği, her ikisini de isteğe bağlı olarak içeren CarV2 ve Model öğelerine sahip Horsepower şemaya göre doğrulanır. Ancak bunun tersi doğru değildir: bir CarV2 örnek, CarV1 şemaya göre doğrulamada başarısız olur.

Geri döngü aynı zamanda bazı ek hususları içermektedir. Daha fazla bilgi içinForward-Compatible Veri Sözleşmeleri'ndeki "Şema Konuları" bölümüne bakın.

İzin Verilen Diğer Değişiklikler

Arayüzü uygulamak IExtensibleDataObject bozmayan bir değişikliktir. Ancak, IExtensibleDataObject uygulandıktan sonraki sürümden önceki tür sürümleri için geri döngü desteği mevcut değildir. Daha fazla bilgi için bkz. Forward-Compatible Veri Sözleşmeleri.

Numaralandırma

Enumerasyon üyesi eklemek veya kaldırmak uyumsuz bir değişikliktir. Bir sabit listesi üyesinin adı değiştirildiğinde, EnumMemberAttribute özniteliği kullanılarak sözleşme adı eski sürümdekiyle aynı tutulmadıkça hatalı olur. Daha fazla bilgi için bkz. Veri Sözleşmelerinde Numaralandırma Türleri.

Koleksiyonlar

Koleksiyon türlerinin çoğu veri sözleşmesi modelinde birbiriyle değiştirilebilir olduğundan koleksiyon değişikliklerinin çoğu bölünemez. Ancak, özelleştirilmemiş bir koleksiyonu özelleştirmek veya tam tersini yapmak, ciddi bir değişikliktir. Ayrıca, koleksiyonun özelleştirme ayarlarını değiştirmek kayda değer bir değişikliktir; yani, veri sözleşmesi adı ve ad alanı, yinelenen öğe adı, anahtar öğe adı ve değer öğe adı değiştirilmektedir. Koleksiyon özelleştirmesi hakkında daha fazla bilgi için bkz. Veri Sözleşmelerindeki Koleksiyon Türleri.
Doğal olarak, bir koleksiyonun içindekiler veri sözleşmesini değiştirmek (örneğin, tamsayı listesinden dize listesine geçmek) hataya neden olan bir değişikliktir.

Ayrıca bakınız

Last updated on 2025-06-17

Aracılığıyla paylaş