DataContractAttribute Klasa

Definicja

Określa, że typ definiuje lub implementuje kontrakt danych i jest możliwy do serializacji przez serializator, taki jak DataContractSerializer .Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Aby można było serializować typ, autorzy muszą definiować kontrakt danych dla ich typu.To make their type serializable, type authors must define a data contract for their type.

public ref class DataContractAttribute sealed : Attribute
public sealed class DataContractAttribute : Attribute
[System.AttributeUsage(System.AttributeTargets.Class | System.AttributeTargets.Enum | System.AttributeTargets.Struct, AllowMultiple=false, Inherited=false)]
public sealed class DataContractAttribute : Attribute
type DataContractAttribute = class
    inherit 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
Dziedziczenie
DataContractAttribute
Atrybuty

Przykłady

Poniższy przykład serializacji i deserializacji klasy o nazwie, Person do której został DataContractAttribute zastosowany.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Należy pamiętać, Namespace że Name właściwości i zostały ustawione na wartości, które zastępują ustawienia domyślne.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 

Uwagi

Zastosuj DataContractAttribute atrybut do typów (klasy, struktury lub wyliczenia), które są używane w operacjach serializacji i deserializacji przez DataContractSerializer .Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. W przypadku wysyłania lub odbierania komunikatów przy użyciu infrastruktury Windows Communication Foundation (WCF) należy również zastosować DataContractAttribute do wszystkich klas, które przechowują dane wysyłane w wiadomości i manipulowanie nimi.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. Aby uzyskać więcej informacji na temat kontraktów danych, zobacz Korzystanie z kontraktów danych.For more information about data contracts, see Using Data Contracts.

Należy również zastosować DataMemberAttribute do dowolnego pola, właściwości lub zdarzenia, które przechowuje wartości, które mają być serializowane.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Stosując DataContractAttribute , jawnie Włącz, DataContractSerializer Aby serializować i deserializować dane.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Przestroga

Można zastosować DataMemberAttribute do pól Private.You can apply the DataMemberAttribute to private fields. Należy pamiętać, że dane zwracane przez pole (nawet jeśli są prywatne) są serializowane i deserializowane, a tym samym może być wyświetlana lub przechwycona przez złośliwego użytkownika lub proces.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.

Aby uzyskać więcej informacji na temat umów dotyczących danych, zobacz tematy wymienione w temacie Using DataContract.For more information about data contracts, see the topics listed in Using Data Contracts.

Kontrakty danychData Contracts

Kontrakt danych to abstrakcyjny opis zestawu pól o nazwie i typie danych dla każdego pola.A data contract is an abstract description of a set of fields with a name and data type for each field. Kontrakt danych istnieje poza żadną pojedynczą implementacją, aby umożliwić współdziałanie usług na różnych platformach.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Tak długo, jak dane przesyłane między usługami są zgodne z tym samym kontraktem, wszystkie usługi mogą przetwarzać dane.As long as the data passed between the services conforms to the same contract, all the services can process the data. To przetwarzanie jest również znane jako luźno połączony system.This processing is also known as a loosely coupled system. Kontrakt danych jest również podobny do interfejsu, w którym kontrakt określa sposób dostarczania danych, tak aby mogły one być przetwarzane przez aplikację.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. Na przykład kontrakt danych może wywoływać typ danych o nazwie "Person", który ma dwa pola tekstowe o nazwie "FirstName" i "LastName".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Aby utworzyć kontrakt danych, Zastosuj DataContractAttribute do klasy i Zastosuj DataMemberAttribute do wszystkich pól lub właściwości, które muszą być serializowane.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Podczas serializacji dane są zgodne z kontraktem danych, który jest niejawnie wbudowany w typ.When serialized, the data conforms to the data contract that is implicitly built into the type.

Uwaga

Kontrakt danych różni się znacznie od rzeczywistego interfejsu w ramach zachowania dziedziczenia.A data contract differs significantly from an actual interface in its inheritance behavior. Interfejsy są dziedziczone przez wszystkie typy pochodne.Interfaces are inherited by any derived types. Po zastosowaniu DataContractAttribute do klasy bazowej typy pochodne nie dziedziczą atrybutu ani zachowania.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Jeśli jednak typ pochodny ma umowę danych, składowe danych klasy bazowej są serializowane.However, if a derived type has a data contract, the data members of the base class are serialized. Należy jednak zastosować DataMemberAttribute do nowych elementów członkowskich w klasie pochodnej, aby je serializować.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Dokumenty schematu XML i narzędzie SvcUtilXML Schema Documents and the SvcUtil Tool

W przypadku wymiany danych z innymi usługami należy opisać umowę dotyczącą danych.If you are exchanging data with other services, you must describe the data contract. W przypadku bieżącej wersji programu DataContractSerializer schemat XML może służyć do definiowania kontraktów danych.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (W tym samym celu można użyć innych form metadanych/opisu). Aby utworzyć schemat XML z aplikacji, użyj Narzędzia metadanych ServiceModel (Svcutil.exe) z opcją wiersza polecenia /dconly .(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. Gdy dane wejściowe narzędzia są zestawem, narzędzie generuje zestaw schematów XML, które definiują wszystkie typy kontraktów danych, które znajdują się w tym zestawie.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. Z kolei można także użyć narzędzia Svcutil.exe, aby utworzyć definicje klas Visual Basic lub C#, które są zgodne z wymaganiami schematów XML, które używają konstrukcji, które mogą być wyrażone przez Kontrakty danych.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. W takim przypadku opcja wiersza polecenia /dconly nie jest wymagana.In this case, the /dconly command line option is not required.

Jeśli dane wejściowe narzędzia Svcutil.exe są schematem XML, narzędzie tworzy zestaw klas.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Jeśli przebadasz te klasy, zobaczysz, że DataContractAttribute został on zastosowany.If you examine those classes, you find that the DataContractAttribute has been applied. Za pomocą tych klas można utworzyć nową aplikację do przetwarzania danych, które muszą być wymieniane z innymi usługami.You can use those classes to create a new application to process data that must be exchanged with other services.

Narzędzie można również uruchomić względem punktu końcowego, który zwraca dokument Web Services Description Language (WSDL), aby automatycznie wygenerować kod i konfigurację w celu utworzenia 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. Wygenerowany kod zawiera typy, które są oznaczone symbolem DataContractAttribute .The generated code includes types that are marked with the DataContractAttribute.

Używanie istniejących typówReusing Existing Types

Kontrakt danych ma dwa podstawowe wymagania: stabilną nazwę i listę członków.A data contract has two basic requirements: a stable name and a list of members. Stabilna nazwa składa się z identyfikatora URI (Uniform Resource Identifier) przestrzeni nazw i nazwy lokalnej kontraktu.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. Domyślnie, gdy stosujesz DataContractAttribute do klasy, używa ona nazwy klasy jako nazwy lokalnej i przestrzeni nazw klasy (poprzedzone prefiksem "http://schemas.datacontract.org/2004/07/" ) jako identyfikator URI przestrzeni nazw.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. Można zastąpić ustawienia domyślne, ustawiając Name Namespace właściwości i.You can override the defaults by setting the Name and Namespace properties. Możesz również zmienić przestrzeń nazw, stosując ContractNamespaceAttribute do przestrzeni nazw.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Użyj tej funkcji, jeśli masz istniejący typ, który przetwarza dane dokładnie tak, jak jest to wymagane, ale ma inną przestrzeń nazw i nazwę klasy z kontraktu danych.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. Zastępując wartości domyślne, można ponownie użyć istniejącego typu, aby serializować dane były zgodne z kontraktem danych.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Uwaga

W dowolnym kodzie można użyć wyrazu DataContract zamiast dłuższej DataContractAttribute .In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Przechowywanie wersjiVersioning

Umowę dotyczącą danych można również uwzględnić w nowszych wersjach.A data contract can also accommodate later versions of itself. Oznacza to, że gdy nowsza wersja kontraktu zawiera dodatkowe dane, dane są przechowywane i zwracane do nadawcy nienaruszone.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. W tym celu Zaimplementuj IExtensibleDataObject interfejs.To do this, implement the IExtensibleDataObject interface.

Aby uzyskać więcej informacji na temat przechowywania wersji, zobacz przechowywanie wersji kontraktu danych.For more information about versioning, see Data Contract Versioning.

Konstruktory

DataContractAttribute()

Inicjuje nowe wystąpienie klasy DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Właściwości

IsNameSetExplicitly

Pobiera, czy został Name jawnie ustawiony.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Pobiera, czy został Namespace jawnie ustawiony.Gets whether Namespace has been explicitly set.

IsReference

Pobiera lub ustawia wartość wskazującą, czy mają być zachowywane dane referencyjne obiektu.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Pobiera, czy został IsReference jawnie ustawiony.Gets whether IsReference has been explicitly set.

Name

Pobiera lub ustawia nazwę kontraktu danych dla typu.Gets or sets the name of the data contract for the type.

Namespace

Pobiera lub ustawia przestrzeń nazw dla kontraktu danych dla typu.Gets or sets the namespace for the data contract for the type.

TypeId

Po zaimplementowaniu w klasie pochodnej pobiera unikatowy identyfikator dla tego elementu Attribute .When implemented in a derived class, gets a unique identifier for this Attribute.

(Odziedziczone po Attribute)

Metody

Equals(Object)

Zwraca wartość wskazującą, czy to wystąpienie jest równe podanemu obiektowi.Returns a value that indicates whether this instance is equal to a specified object.

(Odziedziczone po Attribute)
GetHashCode()

Zwraca wartość skrótu dla tego wystąpienia.Returns the hash code for this instance.

(Odziedziczone po Attribute)
GetType()

Pobiera Type bieżące wystąpienie.Gets the Type of the current instance.

(Odziedziczone po Object)
IsDefaultAttribute()

Gdy jest zastępowany w klasie pochodnej, wskazuje, czy wartość tego wystąpienia jest wartością domyślną klasy pochodnej.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Odziedziczone po Attribute)
Match(Object)

Gdy jest zastępowany w klasie pochodnej, zwraca wartość wskazującą, czy to wystąpienie jest zgodne z określonym obiektem.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Odziedziczone po Attribute)
MemberwiseClone()

Tworzy skróconą kopię bieżącego elementu Object .Creates a shallow copy of the current Object.

(Odziedziczone po Object)
ToString()

Zwraca ciąg reprezentujący bieżący obiekt.Returns a string that represents the current object.

(Odziedziczone po Object)

Jawne implementacje interfejsu

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

Zestaw nazw jest mapowany na odpowiedni zestaw identyfikatorów wysyłania.Maps a set of names to a corresponding set of dispatch identifiers.

(Odziedziczone po Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Pobiera informacje o typie dla obiektu, którego można użyć do uzyskania informacji o typie dla interfejsu.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Odziedziczone po Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Pobiera informację o liczbie typów interfejsów, jakie zawiera obiekt (0 lub 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Odziedziczone po Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Umożliwia dostęp do właściwości i metod udostępnianych przez obiekt.Provides access to properties and methods exposed by an object.

(Odziedziczone po Attribute)

Dotyczy

Zobacz też