Empfohlene Vorgehensweisen: Versionsverwaltung von DatenverträgenBest Practices: Data Contract Versioning

In diesem Thema sind die empfohlenen Vorgehensweisen zum Erstellen von Datenverträgen aufgeführt, die sich im Laufe der Zeit auf einfache Weise entwickeln können.This topic lists the best practices for creating data contracts that can evolve easily over time. Weitere Informationen finden Sie unterFor more information aboutDatenverträgen finden Sie in die Themen in mithilfe von Datenverträgen. data contracts, see the topics in Using Data Contracts.

Hinweis zur SchemavalidierungNote on Schema Validation

Beim Beschreiben der Versionsverwaltung von Datenverträgen ist es wichtig zu wissen, dass das von Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) exportierte Datenvertragsschema nicht über Unterstützung für die Versionsverwaltung verfügt. Die Elemente sind standardmäßig lediglich als optional gekennzeichnet.In discussing data contract versioning, it is important to note that the data contract schema exported by Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) does not have any versioning support, other than the fact that elements are marked as optional by default.

Dies bedeutet, dass sogar ein sehr häufig verwendetes Versionsverwaltungsszenario, beispielsweise das Hinzufügen eines neuen Datenmembers, nicht nahtlos für ein bestimmtes Schema implementiert werden kann.This means that even the most common versioning scenario, such as adding a new data member, cannot be implemented in a way that is seamless with regard to a given schema. Die neueren Versionen eines Datenvertrags (beispielsweise mit einem neuen Datenmember) können bei Verwendung des alten Schemas nicht überprüft werden.The newer versions of a data contract (with a new data member, for example) do not validate using the old schema.

Es gibt jedoch viele Szenarios, bei denen die strenge Schemakompatibilität nicht erforderlich ist.However, there are many scenarios in which strict schema compliance is not required. Viele Webdienstplattformen, zum Beispiel auch WCFWCF und die mithilfe von ASP.NET erstellten XML-Webdienste, führen die Schemavalidierung standardmäßig nicht durch. Aus diesem Grund tolerieren sie zusätzliche Elemente, die vom Schema nicht beschrieben werden.Many Web services platforms, including WCFWCF and XML Web services created using ASP.NET, do not perform schema validation by default and therefore tolerate extra elements that are not described by the schema. Wenn Sie mit Plattformen dieser Art arbeiten, sind viele Versionsverwaltungsszenarios einfacher zu implementieren.When working with such platforms, many versioning scenarios are easier to implement.

Es gibt also zwei Sätze von Richtlinien für die Versionsverwaltung von Datenverträgen: Einen Satz für Szenarios, bei denen die genaue Schemagültigkeit wichtig ist, und einen Satz für Szenarios, bei denen dies nicht wichtig ist.Thus, there are two sets of data contract versioning guidelines: one set for scenarios where strict schema validity is important, and another set for scenarios when it is not.

Versionsverwaltung, wenn eine Schemavalidierung erforderlich istVersioning When Schema Validation Is Required

Wenn die genaue Schemagültigkeit in allen Richtungen erforderlich ist (neu in alt und alt in neu), sollten Datenverträge als unveränderlich angesehen werden.If strict schema validity is required in all directions (new-to-old and old-to-new), data contracts should be considered immutable. Wenn die Versionsverwaltung erforderlich ist, sollte ein neuer Datenvertrag mit einem anderen Namen oder Namespace erstellt werden, und der Dienstvertrag, der den Datentyp nutzt, muss eine entsprechende Version erhalten.If versioning is required, a new data contract should be created, with a different name or namespace, and the service contract using the data type should be versioned accordingly.

Angenommen, Sie verwenden einen Dienstvertrag für die Bestellungsverarbeitung mit dem Namen PoProcessing mit einem PostPurchaseOrder-Vorgang, der einen Parameter erfordert, der einem PurchaseOrder-Datenvertrag entspricht.For example, a purchase order processing service contract named PoProcessing with a PostPurchaseOrder operation takes a parameter that conforms to a PurchaseOrder data contract. Wenn der PurchaseOrder-Vertrag geändert werden muss, müssen Sie einen neuen Datenvertrag erstellen (also PurchaseOrder2), der die Änderungen enthält.If the PurchaseOrder contract has to change, you must create a new data contract, that is, PurchaseOrder2, which includes the changes. Sie müssen die Versionsverwaltung dann auf Dienstvertragsebene behandeln.You must then handle the versioning at the service contract level. Beispiele: Sie erstellen einen PostPurchaseOrder2-Vorgang, der den PurchaseOrder2-Parameter verwendet, oder Sie erstellen einen PoProcessing2-Dienstvertrag, bei dem der PostPurchaseOrder-Vorgang einen PurchaseOrder2-Datenvertrag verwendet.For example, by creating a PostPurchaseOrder2 operation that takes the PurchaseOrder2 parameter, or by creating a PoProcessing2 service contract where the PostPurchaseOrder operation takes a PurchaseOrder2 data contract.

Beachten Sie, dass Änderungen von Datenverträgen, auf die von anderen Datenverträgen verwiesen wird, auch für die Dienstmodellebene gelten.Note that changes in data contracts that are referenced by other data contracts also extend to the service model layer. Angenommen, der PurchaseOrder-Datenvertrag aus dem vorherigen Szenario muss nicht geändert werden.For example, in the previous scenario the PurchaseOrder data contract does not need to change. Er enthält jedoch einen Datenmember eines Customer-Datenvertrags, der wiederum einen Datenmember des Address-Datenvertrags enthält, der allerdings geändert werden muss.However, it contains a data member of a Customer data contract, which in turn contained a data member of the Address data contract, which does need to be changed. In diesem Fall müssen Sie einen Address2-Datenvertrag mit den erforderlichen Änderungen, einen Customer2-Datenvertrag, der den Address2-Datenmember enthält, und einen PurchaseOrder2-Datenvertrag erstellen, der einen Customer2-Datenmember enthält.In that case, you would need to create an Address2 data contract with the required changes, a Customer2 data contract that contains the Address2 data member, and a PurchaseOrder2 data contract that contains a Customer2 data member. Wie im vorherigen Fall muss der Dienstvertrag ebenfalls über eine Versionsangabe verfügen.As in the previous case, the service contract would have to be versioned as well.

Obwohl in diesen Beispielen Namen geändert werden (indem eine "2" angefügt wird), ist es empfehlenswert, anstelle von Namen Namespaces zu ändern, indem neue Namespaces mit einer Versionsnummer oder einem Datum angefügt werden.Although in these examples names are changed (by appending a "2"), the recommendation is to change namespaces instead of names by appending new namespaces with a version number or a date. Der http://schemas.contoso.com/2005/05/21/PurchaseOrder-Datenvertrag würde beispielsweise eine Änderung des http://schemas.contoso.com/2005/10/14/PurchaseOrder-Datenvertrags bewirken.For example, the http://schemas.contoso.com/2005/05/21/PurchaseOrder data contract would change to the http://schemas.contoso.com/2005/10/14/PurchaseOrder data contract.

Weitere Informationen finden Sie unterFor more information, seeBewährte Methoden: Dienstversionsverwaltung. Best Practices: Service Versioning.

In einigen Fällen müssen Sie die genaue Einhaltung für Nachrichten sicherstellen, die von Ihrer Anwendung gesendet werden, können sich jedoch nicht darauf verlassen, dass die eingehenden Nachrichten die Vorgaben des Schemas genau einhalten.Occasionally, you must guarantee strict schema compliance for messages sent by your application, but cannot rely on the incoming messages to be strictly schema-compliant. In diesem Fall besteht die Gefahr, dass eine eingehende Nachricht fremde Daten enthält.In this case, there is a danger that an incoming message might contain extraneous data. Die fremden Werte werden gespeichert und von WCFWCF zurückgegeben, wodurch sich Fehlermeldungen mit dem Hinweis auf ungültige Schemas ergeben.The extraneous values are stored and returned by WCFWCF and thus results in schema-invalid messages being sent. Um dieses Problem zu vermeiden, sollten Sie die Roundtripfunktion deaktivieren.To avoid this problem, the round-tripping feature should be turned off. Hierfür gibt es zwei Möglichkeiten.There are two ways to do this.

Weitere Informationen finden Sie unterFor more information aboutRound-Tripping, finden Sie unter aufwärtskompatible Datenverträge. round-tripping, see Forward-Compatible Data Contracts.

Versionsverwaltung, wenn eine Schemavalidierung nicht erforderlich istVersioning When Schema Validation Is Not Required

Die genaue Schemakompatibilität ist nur selten erforderlich.Strict schema compliance is rarely required. Viele Plattformen tolerieren zusätzliche Elemente, die von einem Schema nicht beschrieben werden.Many platforms tolerate extra elements not described by a schema. Solange diese toleriert wird, der vollständige Satz von Funktionen in der beschriebenen Datenvertragsversionsverwaltung und aufwärtskompatible Datenverträge kann verwendet werden.As long as this is tolerated, the full set of features described in Data Contract Versioning and Forward-Compatible Data Contracts can be used. Die folgenden Richtlinien sind zu empfehlen.The following guidelines are recommended.

Einige Richtlinien müssen exakt befolgt werden, um neue Versionen eines Typs zu senden zu können, wenn ein älterer Typ erwartet wird, bzw. um einen älteren Typ senden zu können, wenn ein neuer Typ erwartet wird.Some of the guidelines must be followed exactly in order to send new versions of a type where an older one is expected or send an old one where the new one is expected. Andere Richtlinien sind nicht unbedingt erforderlich, hier jedoch aufgeführt, da sich die zukünftige Versionsverwaltung von Schemas darauf auswirken kann.Other guidelines are not strictly required, but are listed here because they may be affected by the future of schema versioning.

  1. Versuchen Sie nicht, Datenverträge mit einer Versionsangabe zu versehen, indem Sie die Typvererbung verwenden.Do not attempt to version data contracts by type inheritance. Um höhere Versionen zu erstellen, ändern Sie entweder den Datenvertrag für einen vorhandenen Typ oder erstellen einen neuen nicht verwandten Typ.To create later versions, either change the data contract on an existing type or create a new unrelated type.

  2. Die Verwendung der Vererbung im Zusammenhang mit Datenverträgen ist zulässig, vorausgesetzt, die Vererbung wird nicht als Mechanismus für die Versionsverwaltung verwendet und bestimmte Regeln werden befolgt.The use of inheritance together with data contracts is allowed, provided that inheritance is not used as a versioning mechanism and that certain rules are followed. Wenn ein Typ von einem bestimmten Basistyp abgeleitet ist, sollten Sie diese Ableitung in einer zukünftigen Version nicht in einen anderen Basistyp ändern (es sei denn, dieser verfügt über denselben Datenvertrag).If a type derives from a certain base type, do not make it derive from a different base type in a future version (unless it has the same data contract). Dabei gilt eine Ausnahme: Sie können einen Typ in die Hierarchie zwischen einem Datenvertragstyp und seinem Basistyp einfügen, jedoch nur dann, wenn dieser keine Datenmember mit demselben Namen wie andere Member in beliebigen Versionen der anderen Typen der Hierarchie enthält.There is one exception to this: you can insert a type into the hierarchy between a data contract type and its base type, but only if it does not contain data members with the same names as other members in any possible versions of the other types in the hierarchy. Im Allgemeinen kann die Verwendung von Datenmembern mit demselben Namen auf verschiedenen Ebenen einer Vererbungshierarchie zu ernsthaften Problemen bei der Versionsverwaltung führen. Dies sollte daher vermieden werden.In general, using data members with the same names at different levels of the same inheritance hierarchy can lead to serious versioning problems and should be avoided.

  3. Implementieren Sie immer das IExtensibleDataObject, indem Sie mit der ersten Version eines Datenvertrags beginnen, um Roundtrips zu aktivieren.Starting with the first version of a data contract, always implement IExtensibleDataObject to enable round-tripping. Weitere Informationen finden Sie unterFor more information, seeAufwärtskompatible Datenverträge. Forward-Compatible Data Contracts. Wenn Sie eine oder mehrere Versionen eines Typs veröffentlicht haben, ohne diese Schnittstelle zu implementieren, sollten Sie sie in der nächsten Version des Typs implementieren.If you have released one or more versions of a type without implementing this interface, implement it in the next version of the type.

  4. Ändern Sie den Datenvertragsnamen oder den Namespace in höheren Versionen nicht.In later versions, do not change the data contract name or namespace. Wenn Sie den Namen oder Namespace des Typs ändern, der dem Datenvertrag zugrunde liegt, müssen Sie darauf achten, den Datenvertragsnamen und Namespace beizubehalten, indem Sie die entsprechenden Mechanismen verwenden, zum Beispiel die Name-Eigenschaft des DataContractAttribute.If changing the name or namespace of the type underlying the data contract, be sure to preserve the data contract name and namespace by using the appropriate mechanisms, such as the Name property of the DataContractAttribute. Weitere Informationen finden Sie unterFor more information aboutBenennung, finden Sie unter Datenvertragsnamen. naming, see Data Contract Names.

  5. Nehmen Sie in höheren Versionen keine Änderungen an den Namen von Datenmembern vor.In later versions, do not change the names of any data members. Wenn Sie den Namen des Felds, der Eigenschaft oder des Ereignisses ändern, das bzw. die dem Datenmember zugrunde liegt, können Sie die Name-Eigenschaft des DataMemberAttribute verwenden, um den vorhandenen Datenmembernamen beizubehalten.If changing the name of the field, property, or event underlying the data member, use the Name property of the DataMemberAttribute to preserve the existing data member name.

  6. Nehmen Sie in höheren Versionen keine Änderungen am Typ eines Felds, einer Eigenschaft oder eines einem Datenmember zugrunde liegenden Ereignisses vor, die sich dahingehend auswirken, dass sich der resultierende Datenvertrag für diesen Datenmember ändert.In later versions, do not change the type of any field, property, or event underlying a data member such that the resulting data contract for that data member changes. Denken Sie daran, dass Schnittstellentypen mit Object äquivalent sind, um den erwarteten Datenvertrag ermitteln zu können.Keep in mind that interface types are equivalent to Object for the purposes of determining the expected data contract.

  7. Nehmen Sie in höheren Versionen keine Änderung der Reihenfolge der vorhandenen Datenmember vor, indem Sie die Order-Eigenschaft des DataMemberAttribute-Attributs anpassen.In later versions, do not change the order of the existing data members by adjusting the Order property of the DataMemberAttribute attribute.

  8. In höheren Versionen können neue Datenmember hinzugefügt werden.In later versions, new data members can be added. Sie sollten dabei immer die folgenden Regeln einhalten:They should always follow these rules:

    1. Die IsRequired-Eigenschaft muss immer auf ihrem Standardwert false belassen werden.The IsRequired property should always be left at its default value of false.

    2. Wenn der Standardwert null bzw. "0" für den Member nicht akzeptabel ist, muss mithilfe von OnDeserializingAttribute eine Rückrufmethode bereitgestellt werden, um einen geeigneten Standardwert anzugeben, falls der Member im eingehenden Stream nicht enthalten ist.If a default value of null or zero for the member is unacceptable, a callback method should be provided using the OnDeserializingAttribute to provide a reasonable default in case the member is not present in the incoming stream. Weitere Informationen finden Sie unterFor more information aboutder Rückruf finden Sie unter versionstolerante Serialisierungsrückrufe. the callback, see Version-Tolerant Serialization Callbacks.

    3. Sie sollten die Order-Eigenschaft des DataMemberAttribute verwenden, um sicherzustellen, dass alle neu hinzugefügten Datenmember nach den vorhandenen Datenmembern stehen.The Order property on the DataMemberAttribute should be used to make sure that all of the newly added data members appear after the existing data members. Die empfohlene Vorgehensweise lautet wie folgt: Für keinen Datenmember der ersten Version eines Datenvertrags sollte die Order-Eigenschaft festgelegt sein.The recommended way of doing this is as follows: None of the data members in the first version of the data contract should have their Order property set. Sie sollten für alle Datenmember, die Sie in Version 2 des Datenvertrags hinzugefügt haben, die Order-Eigenschaft auf "2" festlegen.All of the data members added in version 2 of the data contract should have their Order property set to 2. Ebenso sollten Sie die Order-Eigenschaft für in Version 3 des Datenvertrags hinzugefügte Datenmember auf "3" festlegen usw.All of the data members added in version 3 of the data contract should have their Order set to 3, and so on. Es ist zulässig, mehrere Datenmember auf die gleiche Order-Nummer festzulegen.It is permissible to have more than one data member set to the same Order number.

  9. Entfernen Sie Datenmember in höheren Versionen auch dann nicht, wenn die IsRequired-Eigenschaft in den vorherigen Versionen auf der Standardeinstellung false belassen wurde.Do not remove data members in later versions, even if the IsRequired property was left at its default property of false in prior versions.

  10. Ändern Sie die IsRequired-Eigenschaft für vorhandene Datenmember nicht von Version zu Version.Do not change the IsRequired property on any existing data members from version to version.

  11. Ändern Sie die IsRequired-Eigenschaft für erforderliche Datenmember (wobei true den Wert EmitDefaultValue hat) nicht von Version zu Version.For required data members (where IsRequired is true), do not change the EmitDefaultValue property from version to version.

  12. Versuchen Sie nicht, verzweigte Versionsverwaltungshierarchien zu erstellen.Do not attempt to create branched versioning hierarchies. Es sollte also immer ein Pfad in mindestens einer Richtung zwischen Versionen vorhanden sein, indem nur die von diesen Richtlinien zugelassenen Änderungen verwendet werden.That is, there should always be a path in at least one direction from any version to any other version using only the changes permitted by these guidelines.

    Wenn zum Beispiel die Version 1 eines Person-Datenvertrags nur den Name-Datenmember enthält, sollten Sie keine Version 2a des Vertrags erstellen, indem Sie nur den Age-Member hinzufügen, und keine Version 2b, indem Sie nur den Address-Member hinzufügen.For example, if version 1 of a Person data contract contains only the Name data member, you should not create version 2a of the contract adding only the Age member and version 2b adding only the Address member. Der Übergang von 2a zu 2b würde das Entfernen von "Age" und das Hinzufügen von "Address" umfassen. Ein Übergang in der anderen Richtung würde hingegen das Entfernen von "Address" und das Hinzufügen von "Age" umfassen.Going from 2a to 2b would involve removing Age and adding Address; going in the other direction would entail removing Address and adding Age. Das Entfernen von Membern ist im Rahmen dieser Richtlinien nicht zulässig.Removing members is not permitted by these guidelines.

  13. Sie sollten generell keine neuen Untertypen vorhandener Datenvertragstypen in einer neuen Version Ihrer Anwendung erstellen.You should generally not create new subtypes of existing data contract types in a new version of your application. Außerdem sollten Sie keine neuen Datenverträge erstellen, die anstelle von Datenmembern verwendet werden, die als Objekt oder als Schnittstellentypen deklariert sind.Likewise, you should not create new data contracts that are used in place of data members declared as Object or as interface types. Das Erstellen dieser neuen Klassen ist nur zulässig, wenn Sie wissen, dass Sie die neuen Typen der Liste der bekannten Typen aller Instanzen der alten Anwendung hinzufügen können.Creating these new classes is allowed only when you know that you can add the new types to the known types list of all instances of your old application. Es kann zum Beispiel sein, dass Sie in Version 1 Ihrer Anwendung den LibraryItem-Datenvertragstyp mit den Datenvertrags-Untertypen "Buch" und "Zeitung" verwenden.For example, in version 1 of your application, you may have the LibraryItem data contract type with the Book and Newspaper data contract subtypes. "LibraryItem" würde dann über eine Liste der bekannten Typen verfügen, die "Buch" und "Zeitung" enthält.LibraryItem would then have a known types list that contains Book and Newspaper. Angenommen, Sie fügen in Version 2 den Typ "Zeitschrift" hinzu, bei dem es sich um einen Untertyp von "LibraryItem" handelt.Suppose you now add a Magazine type in version 2 which is a subtype of LibraryItem. Wenn Sie eine Zeitschrift-Instanz von Version 2 an Version 1 senden, ist der Zeitschrift-Datenvertrag nicht in der Liste der bekannten Typen enthalten, und es wird eine Ausnahme ausgelöst.If you send a Magazine instance from version 2 to version 1, the Magazine data contract is not found in the list of known types and an exception is thrown.

  14. Sie sollten zwischen Versionen keine Enumerationsmember hinzufügen oder entfernen.You should not add or remove enumeration members between versions. Außerdem sollten Sie Enumerationsmember nicht umbenennen, es sei denn, Sie verwenden die Name-Eigenschaft des EnumMemberAttribute-Attributs, um ihre Namen im Datenvertragsmodell identisch zu halten.You should also not rename enumeration members, unless you use the Name property on the EnumMemberAttribute attribute to keep their names in the data contract model the same.

  15. Sammlungen sind austauschbar im datenvertragsmodell wie beschrieben in Sammlungstypen in Datenverträgen.Collections are interchangeable in the data contract model as described in Collection Types in Data Contracts. Dies ermöglicht einen hohen Grad an Flexibilität.This allows for a great degree of flexibility. Sie sollten jedoch sicherstellen, dass Sie einen Auflistungstyp von Version zu Version nicht versehentlich auf nicht austauschbare Weise ändern.However, make sure that you do not inadvertently change a collection type in a non-interchangeable way from version to version. Wechseln Sie zum Beispiel nicht von einer nicht anpassbaren Auflistung (also ohne CollectionDataContractAttribute-Attribut) zu einer anpassbaren Auflistung oder umgekehrt.For example, do not change from a non-customized collection (that is, without the CollectionDataContractAttribute attribute) to a customized one or a customized collection to a non-customized one. Ändern Sie auch nicht die Eigenschaften für das CollectionDataContractAttribute von Version zu Version.Also, do not change the properties on the CollectionDataContractAttribute from version to version. Die einzige zulässige Änderung ist das Hinzufügen einer Name- oder Namespace-Eigenschaft, wenn sich der Name oder Namespace des zugrunde liegenden Auflistungstyps geändert hat und Sie Name und Namespace des Datenvertrags an den Stand der vorherigen Version anpassen müssen.The only allowed change is adding a Name or Namespace property if the underlying collection type's name or namespace has changed and you need to make its data contract name and namespace the same as in a previous version.

Einige der Richtlinien, die hier aufgelistet sind, können problemlos ignoriert werden, wenn besondere Umstände gelten.Some of the guidelines listed here can be safely ignored when special circumstances apply. Stellen Sie sicher, dass Sie den Mechanismus der Serialisierung, Deserialisierung und Schemaverwendung vollständig verstanden haben, bevor Sie von den Richtlinien abweichen.Make sure you fully understand the serialization, deserialization, and schema mechanisms involved before deviating from the guidelines.

Siehe auchSee Also

Name
DataContractAttribute
Order
IsRequired
IExtensibleDataObject
ServiceBehaviorAttribute
ExtensionData
ExtensionDataObject
OnDeserializingAttribute
Verwenden von DatenverträgenUsing Data Contracts
Datenvertrags-VersionsverwaltungData Contract Versioning
DatenvertragsnamenData Contract Names
Aufwärtskompatible DatenverträgeForward-Compatible Data Contracts
Versionstolerante SerialisierungsrückrufeVersion-Tolerant Serialization Callbacks