DataContractAttribute Třída

Definice

Obor názvů:

System.Runtime.Serialization

Sestavení:

netstandard.dll, System.Runtime.Serialization.Primitives.dll

Zdroj:

DataContractAttribute.cs

Určuje, že typ definuje nebo implementuje datový kontrakt a je serializovatelný serializátorem, například DataContractSerializer. Aby bylo možné typ serializovat, musí autoři typů definovat datový kontrakt pro svůj typ.

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

Dědičnost

Object

Attribute

DataContractAttribute

Atributy

AttributeUsageAttribute

Příklady

Následující příklad serializuje a deserializuje třídu, Person na kterou DataContractAttribute byla použita. Všimněte si, že Namespace vlastnosti a Name vlastnosti byly nastaveny na hodnoty, které přepíší výchozí nastavení.

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

Poznámky

Aplikujte atribut DataContractAttribute na typy (třídy, struktury nebo výčty), které jsou používány v operacích serializace a deserializace DataContractSerializer. Pokud odesíláte nebo přijímáte zprávy pomocí infrastruktury WCF (Windows Communication Foundation), měli byste také použít DataContractAttribute všechny třídy, které uchovávají data a manipulují s daty odesílaných ve zprávách. Další informace o kontraktech dat naleznete v tématu Použití kontraktů dat.

Také musíte DataMemberAttribute aplikovat na jakékoli pole, vlastnost nebo událost, které obsahují hodnoty, jež chcete serializovat. Použitím této možnosti DataContractAttributeexplicitně povolíte DataContractSerializer serializaci a deserializaci dat.

Caution

Na privátní pole můžete aplikovat DataMemberAttribute. Mějte na paměti, že data vrácená polem (i když jsou soukromá) serializována a deserializována, a proto mohou být zobrazena nebo zachycena škodlivým uživatelem nebo procesem.

Další informace o kontraktech dat najdete v tématech uvedených v tématu Používání kontraktů dat.

Datové smlouvy

Kontrakt dat je abstraktní popis sady polí s názvem a datovým typem pro každé pole. Smlouva o datech existuje mimo jakoukoli jednotlivou implementaci, která umožňuje službám na různých platformách spolupracovat. Pokud data předávaná mezi službami odpovídají stejnému kontraktu, můžou data zpracovávat všechny služby. Toto zpracování se také označuje jako volně propojený systém. Kontrakt dat je také podobný rozhraní v tom, že kontrakt určuje, jak musí být data doručena, aby je bylo možné zpracovat aplikací. Například kontrakt dat může specifikovat datový typ s názvem "Osoba", který má dvě textová pole nazvaná "Jméno" a "Příjmení". Chcete-li vytvořit datový kontrakt, aplikujte DataContractAttribute na třídu a aplikujte DataMemberAttribute na všechna pole nebo vlastnosti, které musí být serializovány. Při serializaci jsou data v souladu s kontraktem dat, který je implicitně integrovaný do typu.

Note

Kontrakt dat se ve svém chování dědění výrazně liší od skutečného rozhraní. Všechny odvozené typy dědí rozhraní. Pokud použijete DataContractAttribute na základní třídu, odvozené typy nezdědí ani atribut, ani chování. Nicméně, pokud odvozený typ má datový kontrakt, datové členy základní třídy jsou serializovány. Je však nutné použít DataMemberAttribute na nové členy v odvozené třídě, aby byly serializovatelné.

Dokumenty schématu XML a nástroj SvcUtil

Pokud vyměňujete data s jinými službami, je nutné popsat smlouvu o datech. Pro aktuální verzi schématu DataContractSerializerXML lze použít k definování kontraktů dat. (Pro stejný účel lze použít jiné formy metadat a popisu.) Pokud chcete vytvořit schéma XML z vaší aplikace, použijte nástroj ServiceModel Metadata Utility (Svcutil.exe) s možností příkazového řádku /dconly . Když je vstupem do nástroje sestavení, nástroj ve výchozím nastavení vygeneruje sadu schémat XML, která definují všechny typy datových kontraktů nalezené v daném sestavení. Naopak můžete použít nástroj Svcutil.exe k vytvoření definic tříd jazyka Visual Basic nebo C#, které odpovídají požadavkům schémat XML, které používají konstrukty, které mohou být vyjádřeny datovými kontrakty. V tomto případě není vyžadována možnost příkazového řádku /dconly .

Pokud vstup do nástroje Svcutil.exe je ve výchozím nastavení schématem XML, nástroj vytvoří sadu tříd. Pokud tyto třídy prozkoumáte, zjistíte, že DataContractAttribute byla použita. Tyto třídy můžete použít k vytvoření nové aplikace pro zpracování dat, která se musí vyměňovat s jinými službami.

Můžete také spustit nástroj na koncový bod, který vrací dokument WSDL (Web Services Description Language), který automaticky vygeneruje kód a konfiguraci pro vytvoření klienta WCF (Windows Communication Foundation). Vygenerovaný kód obsahuje typy, které jsou označeny znakem DataContractAttribute.

Opakované použití existujících typů

Kontrakt dat má dva základní požadavky: stabilní název a seznam členů. Stabilní název se skládá z identifikátoru URI (Uniform Resource Identifier) oboru názvů a místního názvu smlouvy. Ve výchozím nastavení, když aplikujete DataContractAttribute na třídu, používá název třídy jako místní název a obor názvů třídy (s předponou "http://schemas.datacontract.org/2004/07/") jako URI oboru názvů. Výchozí nastavení můžete přepsat nastavením Name a Namespace vlastností. Obor názvů můžete také změnit použitím ContractNamespaceAttribute k oboru názvů. Tuto funkci použijte, pokud máte existující typ, který zpracovává data přesně tak, jak potřebujete, ale má jiný obor názvů a název třídy z kontraktu dat. Přepsáním výchozích hodnot můžete znovu použít existující typ a mít serializovaná data v souladu se smlouvou o datech.

Note

V libovolném kódu můžete použít slovo DataContract místo delšího DataContractAttribute.

Verzování

Datový kontrakt může také pojmout novější verze sebe sama. To znamená, že když novější verze kontraktu obsahuje další data, tato data se uloží a vrátí se odesílateli v nezměněné podobě. Provedete to implementací IExtensibleDataObject rozhraní.

Další informace o verzování naleznete v Verzování datového kontraktu.

Konstruktory

Name	Description
DataContractAttribute()	Inicializuje novou instanci DataContractAttribute třídy.

Vlastnosti

Name	Description
IsNameSetExplicitly	Získá, zda Name byl explicitně nastaven.
IsNamespaceSetExplicitly	Získá, zda Namespace byl explicitně nastaven.
IsReference	Získá nebo nastaví hodnotu, která určuje, zda zachovat odkazová data objektu.
IsReferenceSetExplicitly	Získá, zda IsReference byl explicitně nastaven.
Name	Získá nebo nastaví název datového kontraktu pro typ.
Namespace	Nastaví nebo získá obor názvů pro datový kontrakt daného typu.
TypeId	Při implementaci v odvozené třídě získá jedinečný identifikátor pro tento Attribute. (Zděděno od Attribute)

Metody

Name	Description
Equals(Object)	Vrátí hodnotu, která určuje, zda je tato instance rovna zadanému objektu. (Zděděno od Attribute)
GetHashCode()	Vrátí kód hash pro tuto instanci. (Zděděno od Attribute)
GetType()	Získá Type aktuální instance. (Zděděno od Object)
IsDefaultAttribute()	Při přepsání v odvozené třídě určuje, zda hodnota této instance je výchozí hodnotou pro odvozenou třídu. (Zděděno od Attribute)
Match(Object)	Při přepsání v odvozené třídě vrátí hodnotu, která určuje, zda se tato instance rovná zadanému objektu. (Zděděno od Attribute)
MemberwiseClone()	Vytvoří mělkou kopii aktuálního Object. (Zděděno od Object)
ToString()	Vrátí řetězec, který představuje aktuální objekt. (Zděděno od Object)

Viz také

• IExtensibleDataObject
• ExtensionDataObject
• DataContractSerializer
• DataMemberAttribute
• ISerializable
• KnownTypeAttribute
• Použití kontraktů dat