Osvědčené postupy: Správa verzí kontraktů dat

  • Článek

Toto téma obsahuje seznam osvědčených postupů pro vytváření kontraktů dat, které se můžou snadno v průběhu času vyvíjet. Další informace o kontraktech dat najdete v tématech používání kontraktů dat.

Poznámka k ověření schématu

Při diskusi o správě verzí kontraktů dat je důležité si uvědomit, že schéma kontraktu dat exportované službou Windows Communication Foundation (WCF) nemá žádnou podporu správy verzí, kromě skutečnosti, že prvky jsou ve výchozím nastavení označené jako volitelné.

To znamená, že i nejběžnější scénář správy verzí, například přidání nového datového členu, nelze implementovat způsobem, který je bezproblémový s ohledem na dané schéma. Novější verze kontraktu dat (například s novým datovým členem) neověřují použití starého schématu.

Existuje však mnoho scénářů, ve kterých není vyžadováno striktní dodržování předpisů schématu. Mnoho platforem webových služeb, včetně webových služeb WCF a XML vytvořených pomocí ASP.NET, ve výchozím nastavení neprovádí ověřování schématu, a proto tolerovat další prvky, které nejsou popsány schématem. Při práci s těmito platformami je snazší implementovat mnoho scénářů správy verzí.

Existují tedy dvě sady pokynů pro správu verzí kontraktů dat: jedna sada pro scénáře, kdy je důležitá striktní platnost schématu, a další sada pro scénáře, kdy ne.

Správa verzí při vyžadování ověření schématu

Pokud je vyžadována striktní platnost schématu ve všech směrech (nové a staré a staré k novému), měly by být kontrakty dat považovány za neměnné. Pokud se vyžaduje správa verzí, měla by se vytvořit nová datová smlouva s jiným názvem nebo oborem názvů a kontrakt služby používající datový typ by měl být odpovídajícím způsobem verze.

Například smlouva o zpracování nákupní objednávky s názvem PoProcessingPostPurchaseOrder operace přebírá parametr, který odpovídá PurchaseOrder datové smlouvě. PurchaseOrder Pokud se smlouva musí změnit, musíte vytvořit nový datový kontrakt, to znamená , PurchaseOrder2který zahrnuje změny. Správu verzí pak musíte zpracovat na úrovni kontraktu služby. Například vytvořením PostPurchaseOrder2 operace, která přebírá PurchaseOrder2 parametr, nebo vytvořením PoProcessing2 kontraktu služby, kde PostPurchaseOrder operace přebírá PurchaseOrder2 datový kontrakt.

Všimněte si, že změny kontraktů dat, na které odkazují jiné kontrakty dat, se také rozšiřují na vrstvu modelu služby. Například v předchozím scénáři PurchaseOrder se kontrakt dat nemusí měnit. Obsahuje však datový člen datového Customer kontraktu, který zase obsahoval datový člen datového kontraktu Address , který je potřeba změnit. V takovém případě byste museli vytvořit Address2 datový kontrakt s požadovanými změnami, Customer2 datovým kontraktem obsahujícím Address2 datový člen a PurchaseOrder2 datový kontrakt, který obsahuje Customer2 datový člen. Stejně jako v předchozím případě by smlouva o poskytování služeb musela být také verze.

I když se v těchto příkladech mění (připojením "2"), doporučujeme změnit obory názvů místo názvů přidáním nových oborů názvů s číslem verze nebo datem. Například kontrakt http://schemas.contoso.com/2005/05/21/PurchaseOrder dat by se změnil na http://schemas.contoso.com/2005/10/14/PurchaseOrder kontrakt dat.

Další informace najdete v tématu Osvědčené postupy: Správa verzí služby.

V některých případech musíte zaručit striktní dodržování schématu pro zprávy odeslané vaší aplikací, ale nemůžete spoléhat na příchozí zprávy, aby byly přísně kompatibilní se schématem. V tomto případě existuje nebezpečí, že příchozí zpráva může obsahovat nadbytečná data. Nadbytečné hodnoty jsou uloženy a vráceny WCF a výsledkem je odesílání zpráv neplatných schémat. Aby se tomuto problému zabránilo, měla by být funkce odezvy vypnutá. Můžete to provést dvěma způsoby.

Další informace o odezvě naleznete v tématu Kontrakty dat kompatibilní s předáváním.

Správa verzí v případě, že se nevyžaduje ověření schématu

Striktní dodržování předpisů schématu se vyžaduje jen zřídka. Mnoho platforem toleruje dodatečné prvky, které nejsou popsány schématem. Pokud je tolerováno, lze použít úplnou sadu funkcí popsaných ve správě verzí kontraktů dat a kontraktech dat kompatibilních s předáváním. Doporučuje se následující pokyny.

Některé pokyny musí být dodrženy přesně, aby bylo možné odeslat nové verze typu, kde se očekává starší verze, nebo odeslat starý, kde se očekává nový. Další pokyny nejsou přísně vyžadovány, ale jsou zde uvedeny, protože mohou být ovlivněny budoucí verzí schématu.

  1. Nepokoušejte se o verze datových kontraktů podle dědičnosti typů. Pokud chcete vytvořit novější verze, změňte kontrakt dat na existujícím typu nebo vytvořte nový nesouvisející typ.

  2. Použití dědičnosti společně s datovými kontrakty je povoleno, pokud se dědičnost nepoužívá jako mechanismus správy verzí a že jsou dodržena určitá pravidla. Pokud je typ odvozen od určitého základního typu, nevytvrzujte ho z jiného základního typu v budoucí verzi (pokud nemá stejný datový kontrakt). Existuje jedna výjimka: Typ můžete vložit do hierarchie mezi datovým typem kontraktu a jeho základním typem, ale pouze v případě, že neobsahuje datové členy se stejnými názvy jako ostatní členy v jakékoli možné verzi ostatních typů v hierarchii. Obecně platí, že použití datových členů se stejnými názvy na různých úrovních stejné hierarchie dědičnosti může vést k vážným problémům se správou verzí a mělo by se jim vyhnout.

  3. Počínaje první verzí datového kontraktu vždy implementujte IExtensibleDataObject povolení odezvy. Další informace najdete v tématu Kontrakty dat kompatibilní s předáváním. Pokud jste vydali jednu nebo více verzí typu bez implementace tohoto rozhraní, implementujte ji v další verzi typu.

  4. V novějších verzích neměňte název datového kontraktu ani obor názvů. Pokud změníte název nebo obor názvů typu podkladového datového kontraktu, nezapomeňte zachovat název datového kontraktu a obor názvů pomocí příslušných mechanismů, jako Name je například vlastnost DataContractAttribute. Další informace o pojmenování naleznete v tématu Názvy kontraktů dat.

  5. V novějších verzích neměňte názvy žádných datových členů. Pokud změníte název pole, vlastnosti nebo události podkladového datového člena, použijte Name vlastnost datového členu k zachování existujícího názvu datového DataMemberAttribute členu.

  6. V pozdějších verzích nezměníte typ žádného pole, vlastnosti nebo události podkladového datového člena tak, aby se výsledný datový kontrakt pro daného datového člena změnil. Mějte na paměti, že typy rozhraní jsou ekvivalentní Object pro účely určení očekávaného kontraktu dat.

  7. V pozdějších verzích nezměníte pořadí existujících datových členů úpravou Order vlastnosti atributu DataMemberAttribute .

  8. V novějších verzích je možné přidat nové datové členy. Vždy by měly dodržovat tato pravidla:

    1. Vlastnost IsRequired by měla být vždy ponechána na výchozí hodnotě false.

    2. Pokud je pro člena nepřijatelná výchozí hodnota null nebo nula, měla by být k dispozici metoda zpětného volání, OnDeserializingAttribute která poskytuje přiměřené výchozí nastavení v případě, že člen není v příchozím datovém proudu. Další informace o zpětném volání naleznete v tématu Zpětná volání serializace odolné proti verzi.

    3. Vlastnost DataMemberAttribute.Order by se měla použít k zajištění toho, aby se všechny nově přidané datové členy zobrazovaly za existujícími datovými členy. Doporučený způsob, jak to udělat, je následující: Žádná z datových členů v první verzi datové smlouvy by měla mít nastavenou vlastnost Order . Všichni členové dat přidaní ve verzi 2 datového kontraktu by měli mít vlastnost Order nastavenou na hodnotu 2. Všichni členové dat přidaní ve verzi 3 datové smlouvy by měli mít nastavenou Order hodnotu 3 atd. Je přípustné mít více než jeden datový člen nastavený na stejné Order číslo.

  9. Neodebívejte datové členy v novějších verzích, i když IsRequired byla vlastnost ponechána ve své výchozí vlastnosti false v předchozích verzích.

  10. Neměňte vlastnost u žádného existujícího datového IsRequired člena z verze na verzi.

  11. U požadovaných datových členů (kde IsRequired je true) neměňte EmitDefaultValue vlastnost z verze na verzi.

  12. Nepokoušejte se vytvářet hierarchie větvených verzí. To znamená, že by vždy měla existovat cesta alespoň jedním směrem od jakékoli verze k jakékoli jiné verzi, a to pouze pomocí změn povolených těmito pokyny.

    Pokud například verze 1 datového kontraktu osoby obsahuje pouze jméno datového člena, neměli byste vytvořit verzi 2a smlouvy, která přidává pouze věkového člena a verzi 2b, a přidat pouze člena Adresy. Přechod z 2a na 2b by zahrnoval odebrání věku a přidání adresy; v opačném směru by znamenalo odebrání adresy a přidání věku. Odebrání členů není těmito pokyny povoleno.

  13. Obecně byste neměli vytvářet nové podtypy existujících datových kontraktů v nové verzi aplikace. Stejně tak byste neměli vytvářet nové datové kontrakty, které se používají místo datových členů deklarovaných jako Objekt nebo jako typy rozhraní. Vytváření těchto nových tříd je povoleno pouze v případě, že víte, že můžete nové typy přidat do seznamu známých typů všech instancí vaší staré aplikace. Například ve verzi 1 vaší aplikace můžete mít datový kontrakt LibraryItem s podtypy kontraktu Book and Newspaper data contract. KnihovnaItem by pak měla seznam známých typů, který obsahuje knihy a noviny. Předpokládejme, že teď přidáte typ časopisu ve verzi 2, což je podtyp LibraryItem. Pokud odešlete instanci časopisu z verze 2 do verze 1, datový kontrakt Magazine nebyl nalezen v seznamu známých typů a je vyvolán výjimka.

  14. Mezi verzemi byste neměli přidávat ani odebírat členy výčtu. Také byste neměli přejmenovat členy výčtu, pokud nepoužíváte vlastnost Name u EnumMemberAttribute atributu k zachování jejich názvů v modelu kontraktu dat stejné.

  15. Kolekce jsou v modelu kontraktů dat zaměnitelné, jak je popsáno v typech kolekcí v datových kontraktech. To umožňuje velkou míru flexibility. Ujistěte se však, že nechtěně nezměníte typ kolekce neměnitelným způsobem z verze na verzi. Například neměňte z nepřizpůsobené kolekce (tj. bez atributu CollectionDataContractAttribute ) na přizpůsobenou kolekci nebo přizpůsobenou kolekci na nepřizpůsobenou kolekci. Také neměňte vlastnosti CollectionDataContractAttribute verze na verzi. Jedinou povolenou změnou je přidání vlastnosti Název nebo Obor názvů v případě, že se změnil název nebo obor názvů podkladového typu kolekce a je nutné, aby byl název datového kontraktu a obor názvů stejný jako v předchozí verzi.

Některé zde uvedené pokyny mohou být při použití zvláštních okolností bezpečně ignorovány. Před odcházením od pokynů se ujistěte, že plně rozumíte serializaci, deserializaci a mechanismy schématu.

Viz také