DataContractAttribute Třída

Definice

Určuje, že typ definuje nebo implementuje kontrakt dat a je serializovatelný pomocí serializátoru, například DataContractSerializer .Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Aby bylo možné serializovat jejich typ, musí autoři typů definovat kontrakt dat pro svůj typ.To make their type serializable, type authors must define a data contract for their type.

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
DataContractAttribute
Atributy

Příklady

Následující příklad serializace a deserializace třídu s názvem Person , na kterou byla DataContractAttribute použita.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Všimněte si, Namespace že Name vlastnosti a byly nastaveny na hodnoty, které přepíší výchozí nastavení.Note that the Namespace and Name properties have been set to values that override the default settings.

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

Použijte DataContractAttribute atribut na typy (třídy, struktury nebo výčty), které se používají v operacích serializace a deserializace pomocí DataContractSerializer .Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. Pokud odesíláte nebo přijímáte zprávy pomocí infrastruktury Windows Communication Foundation (WCF), měli byste také použít DataContractAttribute pro všechny třídy, které uchovávají a manipulují s daty odesílanými ve zprávách.If you send or receive messages by using the Windows Communication Foundation (WCF) infrastructure, you should also apply the DataContractAttribute to any classes that hold and manipulate data sent in messages. Další informace o kontraktech dat najdete v tématu Použití kontraktů dat.For more information about data contracts, see Using Data Contracts.

Musíte také použít DataMemberAttribute pro jakékoli pole, vlastnost nebo událost, které obsahují hodnoty, které chcete serializovat.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Použitím rozhraní DataContractAttribute , explicitně povolíte DataContractSerializer serializaci a deserializaci dat.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Upozornění

Můžete použít DataMemberAttribute pro soukromá pole.You can apply the DataMemberAttribute to private fields. Počítejte s tím, že data vrácená polem (i když je soukromá) jsou serializovaná a deserializovaná, a proto je lze zobrazit nebo zachytit škodlivým uživatelem nebo procesem.Be aware that the data returned by the field (even if it is private) is serialized and deserialized, and thus can be viewed or intercepted by a malicious user or process.

Další informace o kontraktech dat najdete v tématech uvedených v tématu Použití kontraktů dat.For more information about data contracts, see the topics listed in Using Data Contracts.

Kontrakty datData Contracts

Kontrakt dat je abstraktní Popis sady polí s názvem a datovým typem pro každé pole.A data contract is an abstract description of a set of fields with a name and data type for each field. Kontrakt dat existuje mimo jednu implementaci, která umožňuje vzájemnou spolupráci služeb na různých platformách.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Pokud data předaná mezi službami odpovídají stejné smlouvě, můžou data zpracovávat všechny služby.As long as the data passed between the services conforms to the same contract, all the services can process the data. Tento proces se označuje také jako volně vázaný systém.This processing is also known as a loosely coupled system. Kontrakt dat je také podobný rozhraní v tom, že kontrakt Určuje, jak se mají data doručovat, aby je bylo možné zpracovat pomocí aplikace.A data contract is also similar to an interface in that the contract specifies how data must be delivered so that it can be processed by an application. Kontrakt dat může například volat datový typ s názvem Person, který má dvě textová pole s názvem FirstName a LastName.For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Chcete-li vytvořit kontrakt dat, použijte DataContractAttribute pro třídu a použijte u DataMemberAttribute všech polí nebo vlastností, které musí být serializovány.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Při serializaci data odpovídají kontraktu dat, který je implicitně integrován do typu.When serialized, the data conforms to the data contract that is implicitly built into the type.

Poznámka

Kontrakt dat se výrazně liší od skutečného rozhraní v jeho chování dědičnosti.A data contract differs significantly from an actual interface in its inheritance behavior. Rozhraní jsou zděděná pomocí všech odvozených typů.Interfaces are inherited by any derived types. Při použití DataContractAttribute pro základní třídu odvozené typy nedědí atribut ani chování.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Nicméně pokud má odvozený typ kontrakt dat, jsou serializace datových členů základní třídy.However, if a derived type has a data contract, the data members of the base class are serialized. Je však nutné použít DataMemberAttribute pro nové členy v odvozené třídě, aby byly serializovatelné.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Dokumenty schématu XML a nástroj SvcUtilXML Schema Documents and the SvcUtil Tool

Pokud vyměňujete data s jinými službami, je třeba popsat kontrakt dat.If you are exchanging data with other services, you must describe the data contract. Pro aktuální verzi rozhraní je DataContractSerializer možné použít schéma XML k definování kontraktů dat.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (Pro stejný účel lze použít jiné formy metadat/popis.) Pokud chcete ze své aplikace vytvořit schéma XML, použijte Nástroj/dconly Svcutil.exe (ServiceModel Metadata Utility) s možností příkazového řádku .(Other forms of metadata/description could be used for the same purpose.) To create an XML schema from your application, use the ServiceModel Metadata Utility Tool (Svcutil.exe) with the /dconly command line option. Když vstup do nástroje je sestavení, nástroj ve výchozím nastavení vygeneruje sadu schémat XML, která definují všechny typy kontraktů dat nalezené v tomto sestavení.When the input to the tool is an assembly, by default, the tool generates a set of XML schemas that define all the data contract types found in that assembly. Naopak můžete také pomocí nástroje Svcutil.exe vytvořit definice třídy Visual Basic nebo C#, které odpovídají požadavkům schémat XML, které používají konstrukce, které mohou být vyjádřeny kontrakty dat.Conversely, you can also use the Svcutil.exe tool to create Visual Basic or C# class definitions that conform to the requirements of XML schemas that use constructs that can be expressed by data contracts. V takovém případě není možnost příkazového řádku /dconly nutná.In this case, the /dconly command line option is not required.

Pokud je vstupem nástroje Svcutil.exe schéma XML, nástroj ve výchozím nastavení vytvoří sadu tříd.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Pokud prohlížíte tyto třídy, zjistíte, že byla DataContractAttribute použita.If you examine those classes, you find that the DataContractAttribute has been applied. Tyto třídy můžete použít k vytvoření nové aplikace pro zpracování dat, která musí být vyměněna s jinými službami.You can use those classes to create a new application to process data that must be exchanged with other services.

Nástroj můžete také spustit pro koncový bod, který vrací dokument WSDL (Web Services Description Language) a automaticky vygeneruje kód a konfiguraci pro vytvoření klienta Windows Communication Foundation (WCF).You can also run the tool against an endpoint that returns a Web Services Description Language (WSDL) document to automatically generate the code and configuration to create an Windows Communication Foundation (WCF) client. Generovaný kód obsahuje typy, které jsou označeny atributem DataContractAttribute .The generated code includes types that are marked with the DataContractAttribute.

Znovu se používají existující typy.Reusing Existing Types

Kontrakt dat má dva základní požadavky: stabilní název a seznam členů.A data contract has two basic requirements: a stable name and a list of members. Stabilní název se skládá z oboru názvů identifikátoru URI (Uniform Resource Identifier) a místního názvu kontraktu.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. Ve výchozím nastavení se při použití DataContractAttribute třídy 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 identifikátor URI oboru názvů.By default, when you apply the DataContractAttribute to a class, it uses the class name as the local name and the class's namespace (prefixed with "http://schemas.datacontract.org/2004/07/") as the namespace URI. Výchozí hodnoty můžete přepsat nastavením Name Namespace vlastností a.You can override the defaults by setting the Name and Namespace properties. Můžete také změnit obor názvů tím, že použijete na ContractNamespaceAttribute obor názvů.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Tuto možnost použijte, pokud máte existující typ, který zpracovává data přesně podle potřeby, ale má jiný obor názvů a název třídy od kontraktu dat.Use this capability when you have an existing type that processes data exactly as you require but has a different namespace and class name from the data contract. Přepsáním výchozích hodnot můžete znovu použít stávající typ a Serializovaná data budou odpovídat kontraktu dat.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Poznámka

V jakémkoli kódu můžete DataContract místo toho použít slovo DataContractAttribute .In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Správa verzíVersioning

Kontrakt dat může také pojmout novější verze sebe sama.A data contract can also accommodate later versions of itself. To znamená, že pokud novější verze kontraktu zahrnuje další data, data se ukládají a vrátí odesilateli.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. K tomu je potřeba implementovat IExtensibleDataObject rozhraní.To do this, implement the IExtensibleDataObject interface.

Další informace o tom, jak se správou verzí, najdete v tématu Správa verzí kontraktů dat.For more information about versioning, see Data Contract Versioning.

Konstruktory

DataContractAttribute()

Inicializuje novou instanci DataContractAttribute třídy.Initializes a new instance of the DataContractAttribute class.

Vlastnosti

IsNameSetExplicitly

Získá, zda byl Name explicitně nastaven.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Získá, zda byl Namespace explicitně nastaven.Gets whether Namespace has been explicitly set.

IsReference

Získává nebo nastavuje hodnotu, která indikuje, jestli se mají zachovat referenční data objektů.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Získá, zda byl IsReference explicitně nastaven.Gets whether IsReference has been explicitly set.

Name

Získá nebo nastaví název kontraktu dat pro daný typ.Gets or sets the name of the data contract for the type.

Namespace

Získá nebo nastaví obor názvů pro kontrakt dat pro daný typ.Gets or sets the namespace for the data contract for the type.

TypeId

Při implementaci v odvozené třídě získá jedinečný identifikátor Attribute .When implemented in a derived class, gets a unique identifier for this Attribute.

(Zděděno od Attribute)

Metody

Equals(Object)

Vrací hodnotu, která určuje, zda je tato instance rovna zadanému objektu.Returns a value that indicates whether this instance is equal to a specified object.

(Zděděno od Attribute)
GetHashCode()

Vrátí hodnotu hash pro tuto instanci.Returns the hash code for this instance.

(Zděděno od Attribute)
GetType()

Získá Type aktuální instanci.Gets the Type of the current instance.

(Zděděno od Object)
IsDefaultAttribute()

Při přepsání v odvozené třídě označuje, zda je hodnota této instance výchozí hodnotou pro odvozenou třídu.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Zděděno od Attribute)
Match(Object)

Při přepsání v odvozené třídě vrátí hodnotu, která označuje, zda je tato instance rovna zadanému objektu.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Zděděno od Attribute)
MemberwiseClone()

Vytvoří kopii aktuálního seznamu Object .Creates a shallow copy of the current Object.

(Zděděno od Object)
ToString()

Vrátí řetězec, který představuje aktuální objekt.Returns a string that represents the current object.

(Zděděno od Object)

Explicitní implementace rozhraní

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

Mapuje sadu názvů na odpovídající sadu identifikátorů pro rozesílání.Maps a set of names to a corresponding set of dispatch identifiers.

(Zděděno od Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Načte informace o typu pro objekt, který lze použít k získání informací o typu pro rozhraní.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Zděděno od Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Získá počet rozhraní typu informací, které objekt poskytuje (0 nebo 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Zděděno od Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Poskytuje přístup k vlastnostem a metodám vystaveným objektem.Provides access to properties and methods exposed by an object.

(Zděděno od Attribute)

Platí pro

Viz také