Správa verzí kontraktů dat

S vývojem aplikací můžete také muset změnit kontrakty dat, které služby používají. Toto téma vysvětluje, jak verzovat datové smlouvy. Toto téma popisuje mechanismy správy verzí kontraktů dat. Kompletní přehled a doprovodné materiály k verzím najdete v tématu Osvědčené postupy: Správa verzí kontraktů dat.

Rozbíjející vs. nefunkční změny

Změny v datovém kontraktu mohou být zásadní nebo nezásadní. Když se kontrakt dat změní bez porušení, aplikace používající starší verzi kontraktu může komunikovat s aplikací pomocí novější verze a aplikace používající novější verzi kontraktu může komunikovat s aplikací pomocí starší verze. Na druhou stranu zásadní změna zabraňuje komunikaci v jednom nebo obou směrech.

Všechny změny typu, které nemají vliv na způsob přenosu a přijetí, jsou nepřerušující. Takové změny nemění kontrakt dat, pouze základní typ. Například můžete změnit název pole beze změny funkcionality, pokud pak nastavíte vlastnost Name objektu DataMemberAttribute na název starší verze. Následující kód ukazuje verzi 1 datového kontraktu.

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

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

Následující kód znázorňuje nepřerušující změnu.

// 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

Některé změny upravují přenášená data, ale nemusí nutně být kritické. Následující změny jsou vždy zásadní:

Změna hodnoty Name nebo Namespace datového kontraktu.
Úprava pořadí datových členů pomocí vlastnosti Order z DataMemberAttribute.
Přejmenování datového členu
Změna datového kontraktu člena datové struktury Například změna typu datového členu z celého čísla na řetězec nebo z typu s datovým kontraktem s názvem "Zákazník" na typ s datovým kontraktem s názvem "Osoba".

Je také možné provést následující změny.

Přidávání a odebírání datových členů

Ve většině případů není přidání nebo odebrání datového členu zásadní změnou, pokud nevyžadujete striktní platnost schématu (nové instance validující proti starému schématu).

Pokud je typ s extra polem deserializován do typu s chybějícím polem, dodatečné informace se ignorují. (Může být také uložen pro účely zpětné deserializace; další informace najdete v tématu Forward-Compatible Datové smlouvy).

Pokud je typ s chybějícím polem deserializován do typu s dodatečným polem, pole navíc zůstane na výchozí hodnotě, obvykle nula nebo null. (Výchozí hodnota může být změněna. Další informace najdete v tématu Version-Tolerant Zpětné volání serializace.)

Třídu CarV1 můžete například použít na klientovi a třídu CarV2 na službě, nebo můžete třídu CarV1 použít na službě a třídu CarV2 na klientovi.

// 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

Koncový bod verze 2 může úspěšně odesílat data do koncového bodu verze 1. Serializace verze 2 datového kontraktu Car přináší kód XML podobný následujícímu.

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

Modul deserializace na V1 nenajde odpovídající datový člen pole HorsePower a tato data zahodí.

Koncový bod verze 1 může také odesílat data do koncového bodu verze 2. Serializace verze 1 datového kontraktu Car přináší kód XML podobný následujícímu.

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

Deserializátor verze 2 neví, na co nastavit HorsePower pole, protože v příchozím XML nejsou žádná odpovídající data. Místo toho je pole nastaveno na výchozí hodnotu 0.

Požadované datové členy

Datová položka může být označena jako povinná nastavením IsRequired vlastnosti DataMemberAttribute na true hodnotu. Pokud při deserializaci chybí požadovaná data, vyvolá se výjimka místo nastavení datového členu na výchozí hodnotu.

Přidání požadovaného datového členu je zásadní změna. To znamená, že novější typ se dá dál odesílat do koncových bodů se starším typem, ale ne naopak. Odebrání datového členu označeného jako povinného v jakékoli předchozí verzi je také zásadní změnou.

Změna hodnoty vlastnosti z IsRequired na true není zásadní, ale změna z false na false může být zásadní, pokud některé předchozí verze typu nemají příslušný datový člen.

Poznámka:

I když je vlastnost nastavena na IsRequiredtrue, příchozí data mohou být null nebo nula a typ musí být připraven, aby zvládl tuto možnost. Nepoužívejte IsRequired jako bezpečnostní mechanismus k ochraně před špatnými příchozími daty.

Vynechané výchozí hodnoty

Je možné (i když se nedoporučuje) nastavit EmitDefaultValue vlastnost u atributu DataMemberAttribute na false, jak je popsáno v výchozích hodnotách datového členu. Pokud je toto nastavení false, datová proměnná se nevyprodukuje, pokud má svou výchozí hodnotu (obvykle null nebo nula). To není kompatibilní s požadovanými datovými členy v různých verzích dvěma způsoby:

Kontrakt dat s datovým členem, který je vyžadován v jedné verzi, nemůže přijímat výchozí (null nebo nula) data z jiné verze, ve které je EmitDefaultValue datový člen nastaven na false.
Požadovaný datový člen, který má EmitDefaultValue nastavenou hodnotu false , nelze použít k serializaci výchozí hodnoty (null nebo nula), ale může takovou hodnotu přijmout při deserializaci. Tím se vytvoří problém s konverzí dat (data lze sice přečíst, ale stejná data nelze následně zapsat zpět). Proto pokud IsRequired je true a EmitDefaultValue je false v jedné verzi, měla by stejná kombinace platit pro všechny ostatní verze, aby žádná verze datového kontraktu nemohla vytvořit hodnotu, která neumožňuje zpáteční cestu.

Důležité informace o schématu

Vysvětlení toho, jaké schéma se vytváří pro typy datových kontraktů, naleznete v tématu Referenční informace ke schématu kontraktu dat.

Schéma WCF pro typy datových kontraktů neumožňuje verzování. To znamená, že schéma exportované z určité verze typu obsahuje pouze ty datové členy, které jsou v této verzi. IExtensibleDataObject Implementace rozhraní nezmění schéma pro typ.

Datové členy se ve výchozím nastavení exportují do schématu jako volitelné prvky. To znamená, že minOccurs hodnota (atribut XML) je nastavena na 0. Požadované datové členy se exportují s nastavenou minOccurs na hodnotu 1.

Mnoho změn, které se považují za neporušující, je ve skutečnosti prolomových, pokud je vyžadována přísná shoda se schématem. V předchozím příkladu by instance pouze s prvkem CarV1 odpovídala schématu Model (které obsahuje oba prvky CarV2 a Model, ale oba jsou volitelné). Opačný případ však neplatí: instance CarV2 by při ověřování podle schématu CarV1 selhala.

Zpětné transakce také zahrnují některé další úvahy. Další informace najdete v části Aspekty schématu v Forward-Compatible kontraktech dat.

Jiné povolené změny

IExtensibleDataObject Implementace rozhraní je neprolomná změna. Podpora převeditelnosti však neexistuje pro verze typu před verzí, v níž byla IExtensibleDataObject implementována. Další informace najdete v tématu Forward-Compatible datové smlouvy.

Výčty

Přidání nebo odebrání člena výčtu je zásadní změna. Změna názvu člena výčtu se přeruší, pokud jeho název kontraktu není zachován stejně jako ve staré verzi pomocí atributu EnumMemberAttribute . Další informace naleznete v tématu Výčtové typy v kontraktech dat.

Sbírky

Většina změn kolekce je neprolomná, protože většina typů kolekcí je vzájemně zaměnitelná v modelu kontraktu dat. Převést nepřizpůsobenou kolekci na přizpůsobenou nebo naopak je však zásadní změnou. Změna nastavení přizpůsobení kolekce je také zásadní změnou; to znamená, že změna názvu kontraktu dat a oboru názvů, opakující se název elementu, název klíčového elementu a název prvku hodnoty. Další informace o přizpůsobení kolekce naleznete v tématu Typy kolekcí v kontraktech dat.
Změna datového kontraktu obsahu kolekce (například změna ze seznamu celých čísel na seznam řetězců) je zásadní změnou.

Viz také

Last updated on 2025-06-17

Sdílet prostřednictvím