DataContractAttribute Klasa

Definicja

Określa, że typ definiuje lub implementuje kontrakt danych i jest serializowalny przez serializator, taki jak DataContractSerializer. Aby można było serializować ich typ, autorzy typów muszą zdefiniować kontrakt danych dla ich typu.

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
Dziedziczenie
DataContractAttribute
Atrybuty

Przykłady

Poniższy przykład serializuje i deserializuje klasę o nazwie Person , do której zastosowano klasę DataContractAttribute . Zwróć uwagę, że Namespace właściwości i Name zostały ustawione na wartości, które zastępują ustawienia domyślne.

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

DataContractAttribute Zastosuj atrybut do typów (klas, struktur lub wyliczenia), które są używane w operacjach serializacji i deserializacji przez program DataContractSerializer. W przypadku wysyłania lub odbierania komunikatów przy użyciu infrastruktury platformy Windows Communication Foundation (WCF) należy również zastosować do DataContractAttribute wszystkich klas, które przechowują dane wysyłane w komunikatach i manipulują nimi. Aby uzyskać więcej informacji na temat kontraktów danych, zobacz Korzystanie z kontraktów danych.

Należy również zastosować element DataMemberAttribute do dowolnego pola, właściwości lub zdarzenia zawierającego wartości, które mają być serializujące. Stosując metodę DataContractAttribute, jawnie włączysz DataContractSerializer parametr , aby serializować i deserializować dane.

Przestroga

Możesz zastosować element DataMemberAttribute do pól prywatnych. Należy pamiętać, że dane zwrócone przez pole (nawet jeśli są prywatne) są serializowane i deserializowane, a tym samym mogą być wyświetlane lub przechwytywane przez złośliwego użytkownika lub procesu.

Aby uzyskać więcej informacji na temat kontraktów danych, zobacz tematy wymienione w temacie Using Data Contracts (Korzystanie z kontraktów danych).

Kontrakty danych

Kontrakt danych to abstrakcyjny opis zestawu pól z nazwą i typem danych dla każdego pola. Kontrakt danych istnieje poza jedną implementacją, aby umożliwić współdziałanie usług na różnych platformach. Jeśli dane przekazywane między usługami są zgodne z tą samą umową, wszystkie usługi mogą przetwarzać dane. To przetwarzanie jest również nazywane luźno powiązanym systemem. Kontrakt danych jest również podobny do interfejsu w tym, że kontrakt określa sposób dostarczania danych, aby można było je przetworzyć przez aplikację. Na przykład kontrakt danych może wywołać typ danych o nazwie "Person", który ma dwa pola tekstowe o nazwach "FirstName" i "LastName". Aby utworzyć kontrakt danych, zastosuj element DataContractAttribute do klasy i zastosuj DataMemberAttribute element do wszystkich pól lub właściwości, które muszą być serializowane. Po serializacji dane są zgodne z kontraktem danych, który jest niejawnie wbudowany w typ.

Uwaga

Kontrakt danych różni się znacząco od rzeczywistego interfejsu w zachowaniu dziedziczenia. Interfejsy są dziedziczone przez wszelkie typy pochodne. Po zastosowaniu DataContractAttribute elementu do klasy bazowej typy pochodne nie dziedziczą atrybutu ani zachowania. Jeśli jednak typ pochodny ma kontrakt danych, składowe danych klasy bazowej są serializowane. Należy jednak zastosować element DataMemberAttribute do nowych składowych w klasie pochodnej, aby umożliwić ich serializację.

Dokumenty schematu XML i narzędzie SvcUtil

Jeśli wymieniasz dane z innymi usługami, musisz opisać umowę danych. W przypadku bieżącej DataContractSerializerwersji schematu XML może służyć do definiowania kontraktów danych. (Inne formy metadanych/opisu mogą być używane w tym samym celu). Aby utworzyć schemat XML z aplikacji, użyj narzędzia ServiceModel Metadata Tool (Svcutil.exe) z opcją wiersza polecenia /dconly . Gdy dane wejściowe narzędzia są zestawem, domyślnie narzędzie generuje zestaw schematów XML, które definiują wszystkie typy kontraktów danych znalezionych w tym zestawie. Z drugiej strony można również użyć narzędzia Svcutil.exe, aby utworzyć definicje klas Visual Basic lub C#, które są zgodne z wymaganiami schematów XML korzystających z konstrukcji, które mogą być wyrażone przez kontrakty danych. W takim przypadku opcja wiersza polecenia /dconly nie jest wymagana.

Jeśli dane wejściowe narzędzia Svcutil.exe są schematem XML, domyślnie narzędzie tworzy zestaw klas. Jeśli zbadasz te klasy, okaże się, że zastosowano metodę DataContractAttribute . Za pomocą tych klas można utworzyć nową aplikację do przetwarzania danych, które muszą być wymieniane z innymi usługami.

Możesz również uruchomić narzędzie względem punktu końcowego zwracającego dokument WSDL (Web Services Description Language), aby automatycznie wygenerować kod i konfigurację w celu utworzenia klienta programu Windows Communication Foundation (WCF). Wygenerowany kod zawiera typy oznaczone symbolem DataContractAttribute.

Ponowne przy użyciu istniejących typów

Kontrakt danych ma dwa podstawowe wymagania: stabilną nazwę i listę elementów członkowskich. Stabilna nazwa składa się z identyfikatora URI (URI) przestrzeni nazw i nazwy lokalnej kontraktu. Domyślnie podczas stosowania DataContractAttribute klasy do klasy używa ona nazwy klasy jako nazwy lokalnej i przestrzeni nazw klasy (poprzedzonej prefiksem "http://schemas.datacontract.org/2004/07/") jako identyfikatora URI przestrzeni nazw. Wartości domyślne można zastąpić, ustawiając Name właściwości i Namespace . Przestrzeń nazw można również zmienić, stosując ContractNamespaceAttribute element do przestrzeni nazw. 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. Przesłaniając wartości domyślne, można ponownie użyć istniejącego typu i zapewnić zserializowane dane zgodne z kontraktem danych.

Uwaga

W dowolnym kodzie można użyć słowa DataContract zamiast dłuższego DataContractAttribute.

Przechowywanie wersji

Kontrakt danych może również pomieścić nowsze wersje samego siebie. Oznacza to, że gdy nowsza wersja kontraktu zawiera dodatkowe dane, te dane są przechowywane i zwracane do nadawcy nietkniętego. W tym celu zaimplementuj IExtensibleDataObject interfejs.

Aby uzyskać więcej informacji na temat przechowywania wersji, zobacz Przechowywanie wersji kontraktu danych.

Konstruktory

DataContractAttribute()

Inicjuje nowe wystąpienie klasy DataContractAttribute.

Właściwości

IsNameSetExplicitly

Pobiera informację, czy Name została jawnie ustawiona.

IsNamespaceSetExplicitly

Pobiera informację, czy Namespace została jawnie ustawiona.

IsReference

Pobiera lub ustawia wartość wskazującą, czy zachować dane odwołania do obiektu.

IsReferenceSetExplicitly

Pobiera informację, czy IsReference została jawnie ustawiona.

Name

Pobiera lub ustawia nazwę kontraktu danych dla typu.

Namespace

Pobiera lub ustawia przestrzeń nazw dla kontraktu danych dla typu.

TypeId

Po zaimplementowaniu w klasie pochodnej pobiera unikatowy identyfikator dla tego Attributeelementu .

(Odziedziczone po Attribute)

Metody

Equals(Object)

Zwraca wartość wskazującą, czy to wystąpienie jest równe podanemu obiektowi.

(Odziedziczone po Attribute)
GetHashCode()

Zwraca wartość skrótu dla tego wystąpienia.

(Odziedziczone po Attribute)
GetType()

Type Pobiera wartość bieżącego wystąpienia.

(Odziedziczone po Object)
IsDefaultAttribute()

W przypadku zastąpienia w klasie pochodnej wskazuje, czy wartość tego wystąpienia jest wartością domyślną klasy pochodnej.

(Odziedziczone po Attribute)
Match(Object)

Po przesłonięciu w klasie pochodnej zwraca wartość wskazującą, czy to wystąpienie jest równe określonemu obiektowi.

(Odziedziczone po Attribute)
MemberwiseClone()

Tworzy płytkią kopię bieżącego Objectelementu .

(Odziedziczone po Object)
ToString()

Zwraca ciąg reprezentujący bieżący obiekt.

(Odziedziczone po Object)

Jawne implementacje interfejsu

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

Zestaw nazw jest mapowany na odpowiedni zestaw identyfikatorów wysyłania.

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

Pobiera informacje o typie dla obiektu, który może służyć do pobierania informacji o typie dla interfejsu.

(Odziedziczone po Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Pobiera informację o liczbie typów interfejsów, jakie zawiera obiekt (0 lub 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.

(Odziedziczone po Attribute)

Dotyczy

Zobacz też