DataContractAttribute Klasse

Definition

Gibt an, dass der Typ einen Datenvertrag definiert oder implementiert und mit einem Serialisierer wie dem DataContractSerializer serialisierbar ist. Um ihren Typ serialisierbar zu machen, müssen die Autoren hierfür einen Datenvertrag definieren.

public ref class DataContractAttribute sealed : Attribute
[System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Enum | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
public sealed class DataContractAttribute : Attribute
[<System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Enum | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)>]
type DataContractAttribute = class
    inherit Attribute
Public NotInheritable Class DataContractAttribute
Inherits Attribute
Vererbung
DataContractAttribute
Attribute

Beispiele

Im folgenden Beispiel wird eine Klasse mit dem Namen Person serialisiert und deserialisiert, auf die der DataContractAttribute angewendet wurde. Beachten Sie, dass für die Namespace-Eigenschaft und die Name-Eigenschaft Werte festgelegt wurden, die die Standardeinstellungen überschreiben.

namespace DataContractAttributeExample
{
    // Set the Name and Namespace properties to new values.
    [DataContract(Name = "Customer", Namespace = "http://www.contoso.com")]
    class Person : IExtensibleDataObject
    {
        // To implement the IExtensibleDataObject interface, you must also
        // implement the ExtensionData property.
        private ExtensionDataObject extensionDataObjectValue;
        public ExtensionDataObject ExtensionData
        {
            get
            {
                return extensionDataObjectValue;
            }
            set
            {
                extensionDataObjectValue = value;
            }
        }

        [DataMember(Name = "CustName")]
        internal string Name;

        [DataMember(Name = "CustID")]
        internal int ID;

        public Person(string newName, int newID)
        {
            Name = newName;
            ID = newID;
        }
    }

    class Test
    {
        public static void Main()
        {
            try
            {
                WriteObject("DataContractExample.xml");
                ReadObject("DataContractExample.xml");
                Console.WriteLine("Press Enter to end");
                Console.ReadLine();
            }
            catch (SerializationException se)
            {
                Console.WriteLine
                ("The serialization operation failed. Reason: {0}",
                  se.Message);
                Console.WriteLine(se.Data);
                Console.ReadLine();
            }
        }

        public static void WriteObject(string path)
        {
            // Create a new instance of the Person class and
            // serialize it to an XML file.
            Person p1 = new Person("Mary", 1);
            // Create a new instance of a StreamWriter
            // to read and write the data.
            FileStream fs = new FileStream(path,
            FileMode.Create);
            XmlDictionaryWriter writer = XmlDictionaryWriter.CreateTextWriter(fs);
            DataContractSerializer ser =
                new DataContractSerializer(typeof(Person));
            ser.WriteObject(writer, p1);
            Console.WriteLine("Finished writing object.");
            writer.Close();
            fs.Close();
        }
        public static void ReadObject(string path)
        {
            // Deserialize an instance of the Person class
            // from an XML file. First create an instance of the
            // XmlDictionaryReader.
            FileStream fs = new FileStream(path, FileMode.OpenOrCreate);
            XmlDictionaryReader reader =
                XmlDictionaryReader.CreateTextReader(fs, new XmlDictionaryReaderQuotas());

            // Create the DataContractSerializer instance.
            DataContractSerializer ser =
                new DataContractSerializer(typeof(Person));

            // Deserialize the data and read it from the instance.
            Person newPerson = (Person)ser.ReadObject(reader);
            Console.WriteLine("Reading this object:");
            Console.WriteLine(String.Format("{0}, ID: {1}",
            newPerson.Name, newPerson.ID));
            fs.Close();
        }
    }
}
Namespace DataContractAttributeExample
    ' Set the Name and Namespace properties to new values.
    <DataContract(Name := "Customer", [Namespace] := "http://www.contoso.com")>  _
    Class Person
        Implements IExtensibleDataObject
        ' To implement the IExtensibleDataObject interface, you must also
        ' implement the ExtensionData property.
        Private extensionDataObjectValue As ExtensionDataObject 
        
        Public Property ExtensionData() As ExtensionDataObject _
          Implements IExtensibleDataObject.ExtensionData
            Get
                Return extensionDataObjectValue
            End Get
            Set
                extensionDataObjectValue = value
            End Set
        End Property
        
        <DataMember(Name := "CustName")>  _
        Friend Name As String
        
        <DataMember(Name := "CustID")>  _
        Friend ID As Integer
        
        
        Public Sub New(ByVal newName As String, ByVal newID As Integer) 
            Name = newName
            ID = newID
        
        End Sub 
    End Class 
    
    
    Class Test
        
        Public Shared Sub Main() 
            Try
                WriteObject("DataContractExample.xml")
                ReadObject("DataContractExample.xml")
                Console.WriteLine("Press Enter to end")
                Console.ReadLine()
            Catch se As SerializationException
                Console.WriteLine("The serialization operation failed. Reason: {0}", _
                   se.Message)
                Console.WriteLine(se.Data)
                Console.ReadLine()
            End Try
        
        End Sub 
        
        
        Public Shared Sub WriteObject(ByVal path As String) 
            ' Create a new instance of the Person class and 
            ' serialize it to an XML file.
            Dim p1 As New Person("Mary", 1)
            ' Create a new instance of a StreamWriter
            ' to read and write the data.
            Dim fs As New FileStream(path, FileMode.Create)
            Dim writer As XmlDictionaryWriter = XmlDictionaryWriter.CreateTextWriter(fs)
            Dim ser As New DataContractSerializer(GetType(Person))
            ser.WriteObject(writer, p1)
            Console.WriteLine("Finished writing object.")
            writer.Close()
            fs.Close()
        
        End Sub 
        
        Public Shared Sub ReadObject(ByVal path As String) 
            ' Deserialize an instance of the Person class 
            ' from an XML file. First create an instance of the 
            ' XmlDictionaryReader.
            Dim fs As New FileStream(path, FileMode.OpenOrCreate)
            Dim reader As XmlDictionaryReader = XmlDictionaryReader. _
              CreateTextReader(fs, New XmlDictionaryReaderQuotas())
            
            ' Create the DataContractSerializer instance.
            Dim ser As New DataContractSerializer(GetType(Person))
            
            ' Deserialize the data and read it from the instance.
            Dim newPerson As Person = CType(ser.ReadObject(reader), Person)
            Console.WriteLine("Reading this object:")
            Console.WriteLine(String.Format("{0}, ID: {1}", newPerson.Name, newPerson.ID))
            fs.Close()
        
        End Sub 
    End Class 
End Namespace

Hinweise

Wenden Sie das DataContractAttribute-Attribut auf Typen (Klassen, Strukturen oder Enumerationen) an, die bei Serialisierungs- und Deserialisierungsvorgängen vom DataContractSerializer verwendet werden. Wenn Sie Nachrichten mithilfe der Windows Communication Foundation (WCF)-Infrastruktur senden oder empfangen, sollten Sie auch die DataContractAttribute Klassen anwenden, die Daten enthalten und bearbeiten, die in Nachrichten gesendet werden. Weitere Informationen zu Datenverträgen finden Sie unter Verwenden von Datenverträgen.

Sie müssen den DataMemberAttribute auch auf alle Felder, Eigenschaften oder Ereignisse anwenden, die Werte enthalten, die Sie serialisieren möchten. Indem Sie den DataContractAttribute anwenden, aktivieren Sie explizit den DataContractSerializer zum Serialisieren und Deserialisieren der Daten.

Achtung

Sie können den DataMemberAttribute auf private Felder anwenden. Beachten Sie, dass die von dem Feld zurückgegebenen Daten (auch bei privaten Feldern) serialisiert und deserialisiert werden und daher von böswilligen Benutzern oder Vorgängen angezeigt oder abgefangen werden können.

Weitere Informationen zu Datenverträgen finden Sie in den Themen unter Verwendung von Datenverträgen.

Datenverträge

Ein Datenvertrag ist eine abstrakte Beschreibung einer Gruppe von Feldern mit einem Namen und Datentyp für jedes Feld. Der Datenvertrag befindet sich außerhalb einzelner Implementierungen, um die Zusammenarbeit zwischen den Diensten verschiedener Plattformen zu ermöglichen. Solange die zwischen den Diensten übermittelten Daten demselben Vertrag entsprechen, können sie von allen Diensten verarbeitet werden. Diese Verarbeitung wird auch als lose gekoppeltes System bezeichnet. Ein Datenvertrag ist auch mit einer Schnittstelle vergleichbar, da der Vertrag angibt, wie die Daten zu übermitteln sind, um von einer Anwendung verarbeitet werden zu können. Der Datenvertrag kann beispielsweise einen Datentyp mit der Bezeichnung 'Person' erfordern, der zwei Textfelder mit der Bezeichnung 'Vorname' und 'Nachname' enthält. Um einen Datenvertrag zu erstellen, können Sie den DataContractAttribute auf die Klasse anwenden und den DataMemberAttribute auf Felder oder Eigenschaften anwenden, die serialisiert werden müssen. Wenn die Daten serialisiert sind, entsprechen sie dem implizit in den Typ integrierten Datenvertrag.

Hinweis

Ein Datenvertrag unterscheidet sich in seinem Vererbungsverhalten deutlich von einer tatsächlichen Schnittstelle. Schnittstellen werden an abgeleitete Typen vererbt. Wenn Sie den DataContractAttribute auf eine Basisklasse anwenden, erben die abgeleiteten Typen das Attribut oder das Verhalten nicht. Wenn ein abgeleiteter Typ jedoch einen Datenvertrag hat, werden die Datenmember der Basisklasse serialisiert. Sie müssen den DataMemberAttribute jedoch auf neue Member in einer abgeleiteten Klasse anwenden, um sie serialisierbar zu machen.

XML-Schemadokumente und das Tool SvcUtil

Wenn Sie Daten mit anderen Diensten austauschen, muss der Datenvertrag beschrieben werden. Für die aktuelle Version des DataContractSerializer kann ein XML-Schema verwendet werden, um Datenverträge zu definieren. (Andere Formen von Metadaten/Beschreibungen könnten für denselben Zweck verwendet werden.) Um ein XML-Schema aus Ihrer Anwendung zu erstellen, verwenden Sie das ServiceModel Metadata Utility Tool (Svcutil.exe) mit der Befehlszeilenoption "/dconly ". Wenn das Input in Ihr Tool eine Assembly ist, generiert das Tool standardmäßig eine Gruppe von XML-Schemas, die alle in dieser Assembly gefundenen Datenvertragstypen definieren. Umgekehrt können Sie das Tool Svcutil.exe auch verwenden, um den Anforderungen von XML-Schemas entsprechende Klassendefinitionen für Visual Basic oder C# zu erstellen, die Konstrukte verwenden, die durch Datenverträge ausgedrückt werden können. In diesem Fall ist die Befehlszeilenoption /dconly nicht erforderlich.

Wenn in das Tool Svcutil.exe ein XML-Schema eingegeben wird, erstellt das Tool standardmäßig eine Reihe von Klassen. Wenn Sie diese Klassen prüfen, stellen Sie fest, dass der DataContractAttribute verwendet wurde. Sie können diese Klassen verwenden, um eine neue Anwendung zur Verarbeitung von Daten zu erstellen, die mit anderen Diensten ausgetauscht werden müssen.

Sie können das Tool auch für einen Endpunkt ausführen, der ein WSDL-Dokument (Web Services Description Language) zurückgibt, um den Code und die Konfiguration automatisch zu generieren, um einen Windows Communication Foundation (WCF)-Client zu erstellen. Der generierte Code schließt Typen ein, die mit dem DataContractAttribute gekennzeichnet sind.

Wiederverwendung vorhandener Typen

Ein Datenvertrag verfügt über zwei grundlegende Anforderungen: einen stabilen Namen und eine Liste von Membern. Der stabile Name besteht aus dem Namespace-URI (Uniform Resource Identifier) und dem lokalen Namen des Vertrags. Wenn Sie die DataContractAttribute Klasse standardmäßig anwenden, wird der Klassenname als lokaler Name und der Namespace der Klasse (präfixiert mit "http://schemas.datacontract.org/2004/07/") als Namespace-URI verwendet. Diese Standardwerte können durch Festlegen der Eigenschaften Name und Namespace überschrieben werden. Sie können auch den Namespace ändern, indem Sie den ContractNamespaceAttribute auf den Namespace anwenden. Sie können diese Fähigkeit bei einem bestehenden Typ nutzen, der Daten genau nach Ihren Anforderungen verarbeitet, jedoch einen anderen Namespace und Klassennamen aufweist als im Datenvertrag. Durch Überschreiben der Standardwerte können Sie Ihren vorhandenen Typ wiederverwenden und gewährleisten, dass die serialisierten Daten dem Datenvertrag entsprechen.

Hinweis

In jedem Code können Sie das Wort DataContract anstelle des längeren DataContractAttribute verwenden.

Versionskontrolle

Ein Datenvertrag kann auch höhere Versionen seiner selbst nutzen. Wenn eine höhere Version des Vertrags zusätzliche Daten enthält, werden diese Daten gespeichert und unverändert an den Absender zurückgegeben. Hierzu müssen Sie die IExtensibleDataObject-Schnittstelle implementieren.

Weitere Informationen zur Versionsverwaltung finden Sie unter Data Contract Versionsing.

Konstruktoren

DataContractAttribute()

Initialisiert eine neue Instanz der DataContractAttribute-Klasse.

Eigenschaften

IsNameSetExplicitly

Ruft ab, ob Name explizit festgelegt wurde.

IsNamespaceSetExplicitly

Ruft ab, ob Namespace explizit festgelegt wurde.

IsReference

Ruft einen Wert ab oder legt einen Wert fest, der angibt, ob Objektverweisdaten beizubehalten sind.

IsReferenceSetExplicitly

Ruft ab, ob IsReference explizit festgelegt wurde.

Name

Ruft den Namen des Datenvertrags für den Typ ab oder legt ihn fest.

Namespace

Ruft den Namespace des Datenvertrags für den Typ ab oder legt ihn fest.

TypeId

Ruft bei Implementierung in einer abgeleiteten Klasse einen eindeutigen Bezeichner für dieses Attribute ab.

(Geerbt von Attribute)

Methoden

Equals(Object)

Gibt einen Wert zurück, der angibt, ob diese Instanz gleich einem angegebenen Objekt ist.

(Geerbt von Attribute)
GetHashCode()

Gibt den Hashcode für diese Instanz zurück.

(Geerbt von Attribute)
GetType()

Ruft den Type der aktuellen Instanz ab.

(Geerbt von Object)
IsDefaultAttribute()

Gibt beim Überschreiben in einer abgeleiteten Klasse an, ob der Wert der Instanz der Standardwert für die abgeleitete Klasse ist.

(Geerbt von Attribute)
Match(Object)

Beim Überschreiben in einer abgeleiteten Klasse wird ein Wert zurückgegeben, der angibt, ob diese Instanz einem bestimmten Objekt entspricht.

(Geerbt von Attribute)
MemberwiseClone()

Erstellt eine flache Kopie des aktuellen Object.

(Geerbt von Object)
ToString()

Gibt eine Zeichenfolge zurück, die das aktuelle Objekt darstellt.

(Geerbt von Object)

Explizite Schnittstellenimplementierungen

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

Ordnet eine Reihe von Namen einer entsprechenden Reihe von Dispatchbezeichnern zu.

(Geerbt von Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Ruft die Typinformationen für ein Objekt ab, mit deren Hilfe die Typinformationen für eine Schnittstelle abgerufen werden können.

(Geerbt von Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Ruft die Anzahl der Schnittstellen mit Typinformationen ab, die von einem Objekt bereitgestellt werden (0 oder 1).

(Geerbt von Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Stellt den Zugriff auf von einem Objekt verfügbar gemachte Eigenschaften und Methoden bereit.

(Geerbt von Attribute)

Gilt für:

Siehe auch