Verwenden von DatenverträgenUsing Data Contracts

Ein neuer Datenvertrag ist eine formale Vereinbarung zwischen einem Dienst und einem Client, in dem die auszutauschenden Daten abstrakt beschrieben werden.A data contract is a formal agreement between a service and a client that abstractly describes the data to be exchanged. Das heißt, der Client und der Dienst müssen, um kommunizieren zu können, nicht denselben Typ verwenden, sondern nur dieselben Datenverträge.That is, to communicate, the client and the service do not have to share the same types, only the same data contracts. Ein Datenvertrag definiert für jeden Parameter oder Rückgabetyp genau, welche Daten für einen Austausch serialisiert (in XML umgewandelt) werden.A data contract precisely defines, for each parameter or return type, what data is serialized (turned into XML) to be exchanged.

Grundlagen des DatenvertragsData Contract Basics

Windows Communication Foundation (WCF)Windows Communication Foundation (WCF) verwendet zum Serialisieren und Deserialisieren von Daten (Umwandeln in und aus XML) standardmäßig ein Serialisierungsprogramm für Datenverträge (Data Contract Serializer). uses a serialization engine called the Data Contract Serializer by default to serialize and deserialize data (convert it to and from XML). Alle primitiven Typen von .NET Framework.NET Framework , wie Ganzzahlen und Zeichenfolgen, sowie bestimmte als Primitive behandelte Typen, wie DateTime und XmlElement, können ohne weitere Vorbereitung serialisiert werden und sind gewissermaßen mit Standarddatenverträgen ausgestattet.All .NET Framework.NET Framework primitive types, such as integers and strings, as well as certain types treated as primitives, such as DateTime and XmlElement, can be serialized with no other preparation and are considered as having default data contracts. Viele Typen von .NET Framework.NET Framework besitzen auch vorhandene Datenverträge.Many .NET Framework.NET Framework types also have existing data contracts. Eine vollständige Liste der serialisierbaren Typen finden Sie unter Types Supported by the Data Contract Serializer.For a full list of serializable types, see Types Supported by the Data Contract Serializer.

Für neue komplexe Typen, die Sie erstellen, muss ein Datenvertrag definiert sein, damit sie serialisierbar sind.New complex types that you create must have a data contract defined for them to be serializable. Standardmäßig leitet der DataContractSerializer den Datenvertrag ab und serialisiert alle öffentlich sichtbaren Typen.By default, the DataContractSerializer infers the data contract and serializes all publicly visible types. Alle öffentlichen Lese-/Schreibeigenschaften und Felder des Typs werden serialisiert.All public read/write properties and fields of the type are serialized. Mithilfe des IgnoreDataMemberAttributekönnen Member von der Serialisierung ausgeschlossen werden.You can opt out members from serialization by using the IgnoreDataMemberAttribute. Mit dem DataContractAttribute -Attribut und dem DataMemberAttribute -Attribut können Sie auch explizit einen Datenvertrag erstellen.You can also explicitly create a data contract by using DataContractAttribute and DataMemberAttribute attributes. Wenden Sie dazu das DataContractAttribute -Attribut auf den Typ an.This is normally done by applying the DataContractAttribute attribute to the type. Dieses Attribut kann auf Klassen, Strukturen und Enumerationen angewendet werden.This attribute can be applied to classes, structures, and enumerations. Das DataMemberAttribute -Attribut muss dann auf jeden Member des Datenvertragstyps angewendet werden, um anzugeben, dass es sich um einen Datenmemberhandelt, d. h., dass er serialisiert werden soll.The DataMemberAttribute attribute must then be applied to each member of the data contract type to indicate that it is a data member, that is, it should be serialized. Weitere Informationen finden Sie unter serialisierbaren Typen.For more information, see Serializable Types.

BeispielExample

Im folgenden Beispiel wird ein Dienstvertrag (eine Schnittstelle) dargestellt, auf die die Attribute ServiceContractAttribute und OperationContractAttribute explizit angewendet wurden.The following example shows a service contract (an interface) to which the ServiceContractAttribute and OperationContractAttribute attributes have been explicitly applied. Das Beispiel zeigt, dass primitive Typen keinen Datenvertrag erfordern, ein komplexer Typ jedoch schon.The example shows that primitive types do not require a data contract, while a complex type does.

[ServiceContract]
public interface ISampleInterface
{
    // No data contract is required since both the parameter 
    // and return types are primitive types.
    [OperationContract]
    double SquareRoot(int root);

    // No Data Contract required because both parameter and return 
    // types are marked with the SerializableAttribute attribute.
    [OperationContract]
    System.Drawing.Bitmap GetPicture(System.Uri pictureUri);

    // The MyTypes.PurchaseOrder is a complex type, and thus 
    // requires a data contract.
    [OperationContract]
    bool ApprovePurchaseOrder(MyTypes.PurchaseOrder po);
}
<ServiceContract()>  _
Public Interface ISampleInterface
    ' No data contract is required since both the parameter and return 
    ' types are both primitive types.
    <OperationContract()>  _
    Function SquareRoot(ByVal root As Integer) As Double 
    
    ' No Data Contract required because both parameter and return 
    ' types are marked with the SerializableAttribute attribute.
    <OperationContract()>  _
    Function GetPicture(ByVal pictureUri As System.Uri) As System.Drawing.Bitmap 
    
    ' The MyTypes.PurchaseOrder is a complex type, and thus 
    ' requires a data contract.
    <OperationContract()>  _
    Function ApprovePurchaseOrder(ByVal po As MyTypes.PurchaseOrder) As Boolean 
End Interface 

Das folgende Beispiel veranschaulicht, wie Sie einen Datenvertrag für den MyTypes.PurchaseOrder -Typ erstellen, indem Sie die Attribute DataContractAttribute und DataMemberAttribute auf die Klassen und ihre Member anwenden.The following example shows how a data contract for the MyTypes.PurchaseOrder type is created by applying the DataContractAttribute and DataMemberAttribute attributes to the class and its members.

namespace MyTypes
{
    [DataContract]
    public class PurchaseOrder
    {
        private int poId_value;

        // Apply the DataMemberAttribute to the property.
        [DataMember]
        public int PurchaseOrderId
        {

            get { return poId_value; }
            set { poId_value = value; }
        }
    }
}
Namespace MyTypes
    <System.Runtime.Serialization.DataContractAttribute()>  _
    Public Class PurchaseOrder
        Private poId_value As Integer
        
        ' Apply the DataMemberAttribute to the property.
        
        <DataMember()>  _
        Public Property PurchaseOrderId() As Integer 
            
            Get
                Return poId_value
            End Get
            Set
                poId_value = value
            End Set
        End Property
    End Class 
End Namespace 

HinweiseNotes

Berücksichtigen Sie beim Erstellen von Datenverträgen die folgenden Hinweise:The following notes provide items to consider when creating data contracts:

  • Das IgnoreDataMemberAttribute -Attribut wird nur berücksichtigt, wenn es zusammen mit nicht markierten Typen verwendet wird.The IgnoreDataMemberAttribute attribute is only honored when used with unmarked types. Dazu zählen Typen, die weder mit einem DataContractAttribute-, SerializableAttribute-, CollectionDataContractAttribute- oder EnumMemberAttribute -Attribut noch auf andere Weise als serialisierbar markiert sind (beispielsweise mithilfe von IXmlSerializable).This includes types that are not marked with one of the DataContractAttribute, SerializableAttribute, CollectionDataContractAttribute, or EnumMemberAttribute attributes, or marked as serializable by any other means (such as IXmlSerializable).

  • Sie können das DataMemberAttribute -Attribut auf Felder und Eigenschaften anwenden.You can apply the DataMemberAttribute attribute to fields, and properties.

  • Memberzugriffsebenen (internal, private, protected oder public) haben keinerlei Einfluss auf den Datenvertrag.Member accessibility levels (internal, private, protected, or public) do not affect the data contract in any way.

  • Das DataMemberAttribute -Attribut wird ignoriert, wenn es auf statische Member angewendet wird.The DataMemberAttribute attribute is ignored if it is applied to static members.

  • Bei der Serialisierung werden mit einem Aufruf von property-get-Code für Eigenschaftsdatenmember die Werte der zu serialisierenden Eigenschaften abgerufen.During serialization, property-get code is called for property data members to get the value of the properties to be serialized.

  • Bei der Deserialisierung wird zuerst ein nicht initialisiertes Objekt erstellt, ohne dass Konstruktoren für den Typ aufgerufen werden.During deserialization, an uninitialized object is first created, without calling any constructors on the type. Dann werden alle Datenmember deserialisiert.Then all data members are deserialized.

  • Mit einem Aufruf von property-set-Code für Eigenschaftsdatenmember werden bei der Deserialisierung die Werte der zu deserialisierenden Eigenschaften festgelegt.During deserialization, property-set code is called for property data members to set the properties to the value being deserialized.

  • Damit ein Datenvertrag gültig ist, müssen alle seine Datenmember serialisiert werden können.For a data contract to be valid, it must be possible to serialize all of its data members. Eine vollständige Liste der serialisierbaren Typen finden Sie unter Types Supported by the Data Contract Serializer.For a full list of serializable types, see Types Supported by the Data Contract Serializer.

    Generische Typen werden auf genau die gleiche Weise behandelt wie nicht generische Typen.Generic types are handled in exactly the same way as non-generic types. Es gibt keine besonderen Anforderungen für generische Parameter.There are no special requirements for generic parameters. Betrachten Sie z. B. den folgenden Typ:For example, consider the following type.

[DataContract]
public class MyGenericType1<T>
{
    // Code not shown.
}
<DataContract()>  _
Public Class MyGenericType1(Of T)
    ' Code not shown.
End Class

Dieser Typ ist serialisierbar, unabhängig davon, ob der für den generischen Typparameter (T) verwendete Typ serialisierbar ist.This type is serializable whether the type used for the generic type parameter (T) is serializable or not. Da das Serialisieren aller Datenmember möglich sein muss, ist der folgende Typ nur dann serialisierbar, wenn der generische Typparameter ebenfalls serialisierbar ist (wie im folgenden Code dargestellt):Because it must be possible to serialize all data members, the following type is serializable only if the generic type parameter is also serializable, as shown in the following code.

[DataContract]
public class MyGenericType2<T>
{
    [DataMember]
    T theData;
}
<DataContract()>  _
Public Class MyGenericType2(Of T)
    <DataMember()>  _
    Dim theData As T
End Class 

Ein vollständiges Codebeispiel eines WCF-Diensts, der einen Datenvertrag definiert, finden Sie unter Basic Data Contract .For a complete code sample of a WCF service that defines a data contract see the Basic Data Contract sample.

Siehe auchSee Also

DataMemberAttribute
DataContractAttribute
Serialisierbare TypenSerializable Types
DatenvertragsnamenData Contract Names
DatenvertragsäquivalenzData Contract Equivalence
DatenmemberreihenfolgeData Member Order
Bekannte Typen in DatenverträgenData Contract Known Types
Aufwärtskompatible DatenverträgeForward-Compatible Data Contracts
Datenvertrags-VersionsverwaltungData Contract Versioning
Versionstolerante SerialisierungsrückrufeVersion-Tolerant Serialization Callbacks
Standardwerte der DatenelementeData Member Default Values
Vom Datenvertragsserialisierer unterstützte TypenTypes Supported by the Data Contract Serializer
Vorgehensweise: Erstellen eines grundlegenden Datenvertrags für eine Klasse oder StrukturHow to: Create a Basic Data Contract for a Class or Structure