DataContractAttribute Osztály

Definíció

Névtér:

System.Runtime.Serialization

Szerelvények:

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

Forrás:

DataContractAttribute.cs

Megadja, hogy a típus adatszerződést definiál vagy implementál, és szerializálható egy szerializálóval, például a DataContractSerializer. A típus szerializálhatóvá tételéhez a típuskészítőknek meg kell határozniuk egy adatszerződést a típusukhoz.

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

Öröklődés

Object

Attribute

DataContractAttribute

Attribútumok

AttributeUsageAttribute

Példák

Az alábbi példa szerializál és deszerializál egy osztályt Person , amelyre a DataContractAttribute rendszer alkalmazva lett. Vegye figyelembe, hogy a Namespace tulajdonságok olyan Name értékekre lettek beállítva, amelyek felülbírálják az alapértelmezett beállításokat.

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

Megjegyzések

Alkalmazza az attribútumot azokra a DataContractAttribute típusokra (osztályokra, struktúrákra vagy enumerálásokra), amelyeket a szerializálási és deszerializálási műveletekben használ a DataContractSerializer. Ha a Windows kommunikációs alaprendszer (WCF) infrastruktúrájának használatával küld vagy fogad üzeneteket, akkor az üzenetekben küldött adatokat tartalmazó és módosító osztályokra is alkalmaznia kell a DataContractAttribute elemet. További információ az adatszerződésekről: Adatszerződések használata.

A szerializálni kívánt értékeket tartalmazó mezőkre, tulajdonságokra vagy eseményekre is DataMemberAttribute kell alkalmaznia. Az DataContractAttribute alkalmazásával explicit módon engedélyezheti a DataContractSerializer szerializálását és deszerializálását.

Caution

A DataMemberAttribute magánmezőkre alkalmazhatja. Vegye figyelembe, hogy a mező által visszaadott adatok (még ha privátak is) szerializálva és deszerializálva vannak, így rosszindulatú felhasználó vagy folyamat tekintheti meg vagy elfoghatja őket.

Az adatszerződésekkel kapcsolatos további információkért tekintse meg az Adatszerződések használata című témakört.

Adatszerződések

Az adatszerződés az egyes mezők névvel és adattípussal rendelkező mezőkészletének absztrakt leírása. Az adatszerződés egyetlen megvalósításon kívül is létezik, hogy lehetővé tegye a különböző platformokon lévő szolgáltatások együttműködését. Mindaddig, amíg a szolgáltatások között átadott adatok egy szerződésnek felelnek meg, az összes szolgáltatás feldolgozhatja az adatokat. Ezt a feldolgozást lazán összekapcsolt rendszernek is nevezik. Az adatszerződések az interfészhez is hasonlóak, mivel a szerződés meghatározza az adatok kézbesítésének módját, hogy azokat egy alkalmazás feldolgozhassa. Az adatszerződés például meghívhat egy "Person" nevű adattípust, amelynek két szövegmezője van: "FirstName" és "LastName". Adatszerződés létrehozásához alkalmazza a DataContractAttribute az osztályra, és a DataMemberAttribute a szerializálandó mezőkre vagy tulajdonságokra. Szerializált állapotban az adatok megfelelnek a típusba implicit módon beépített adatszerződésnek.

Note

Az adatszerződések jelentősen eltérnek a tényleges interfésztől az öröklési viselkedésében. Az illesztőket bármely leszármaztatott típus örökli. Az alaposztály alkalmazásakor DataContractAttribute a származtatott típusok nem öröklik az attribútumot vagy a viselkedést. Ha azonban egy származtatott típus adatszerződéssel rendelkezik, az alaposztály adattagjainak szerializálása történik. Azonban a DataMemberAttribute-t egy származtatott osztály új tagjaira kell alkalmaznia, hogy azokat szerializálhatóvá tegye.

XML-sémadokumentumok és az SvcUtil eszköz

Ha más szolgáltatásokkal cserél adatokat, le kell írnia az adatszerződést. Az aktuális verzióhoz DataContractSerializerxml-séma használható adatszerződések definiálásához. (Más metaadat-/leírási formák is használhatók ugyanahhoz a célra.) Ha XML-sémát szeretne létrehozni az alkalmazásból, használja a ServiceModel Metadata Segédprogramot (Svcutil.exe) a /dconly parancssori beállítással. Ha az eszköz bemenete egy szerelvény, az eszköz alapértelmezés szerint xml-sémákat hoz létre, amelyek meghatározzák az adott szerelvényben található összes adatszerződés-típust. Ezzel szemben a Svcutil.exe eszközzel olyan Visual Basic- vagy C#-osztálydefiníciókat is létrehozhat, amelyek megfelelnek az adatszerződések által kifejezhető szerkezeteket használó XML-sémák követelményeinek. Ebben az esetben nincs szükség a /dconly parancssori beállításra.

Ha a Svcutil.exe eszköz bemenete XML-séma, az eszköz alapértelmezés szerint osztályokat hoz létre. Ha megvizsgálja ezeket az osztályokat, azt tapasztalja, hogy az DataContractAttribute lett alkalmazva. Ezekkel az osztályokkal létrehozhat egy új alkalmazást olyan adatok feldolgozásához, amelyeket más szolgáltatásokkal kell kicserélni.

Az eszközt egy olyan végponton is futtathatja, amely egy Web Services Description Language (WSDL) dokumentumot ad vissza, és automatikusan létrehozza a kódot és a konfigurációt a Windows kommunikációs alaprendszer (WCF) ügyfél létrehozásához. A létrehozott kód olyan típusokat tartalmaz, amelyek a DataContractAttribute-val vannak megjelölve.

Meglévő típusok újrafelhasználása

Az adatszerződésnek két alapvető követelménye van: egy stabil név és egy taglista. A stabil név a névtér egységes erőforrás-azonosítóját (URI) és a szerződés helyi nevét tartalmazza. Ha egy osztályra alkalmazza az DataContractAttribute osztályt, az alapértelmezés szerint az osztálynevet használja helyi névként, az osztály névterét (előtaggal "http://schemas.datacontract.org/2004/07/") pedig névtér URI-ként. Az alapértelmezett értékeket felülbírálhatja a Name és Namespace tulajdonságok beállításával. A névtér úgy is módosítható, hogy a ContractNamespaceAttribute-t alkalmazza rá. Ezt a képességet akkor használja, ha olyan meglévő típussal rendelkezik, amely pontosan a kívánt módon dolgozza fel az adatokat, de az adatszerződéstől eltérő névtérrel és osztálynévvel rendelkezik. Az alapértelmezett értékek felülírásával újra felhasználhatja a meglévő típust, és megadhatja, hogy a szerializált adatok megfeleljenek az adatszerződésnek.

Note

Bármely kódban használhatja a szót DataContract a hosszabb DataContractAttributehelyett.

Versioning

Az adatszerződések saját maguk későbbi verzióit is képesek befogadni. Vagyis ha a szerződés egy későbbi verziója további adatokat tartalmaz, a rendszer az adatokat érintetlenül tárolja és visszaküldi a feladónak. Ehhez implementálja az interfészt IExtensibleDataObject .

A verziószámozással kapcsolatos további információkért lásd: Adatszerződések verziószámozása.

Konstruktorok

Name	Description
DataContractAttribute()	Inicializálja a DataContractAttribute osztály új példányát.

Tulajdonságok

Name	Description
IsNameSetExplicitly	Lekérdezi, hogy explicit módon lett-e Name beállítva.
IsNamespaceSetExplicitly	Lekérdezi, hogy explicit módon lett-e Namespace beállítva.
IsReference	Lekéri vagy beállít egy értéket, amely jelzi, hogy meg szeretné-e őrizni az objektumhivatkozási adatokat.
IsReferenceSetExplicitly	Lekérdezi, hogy explicit módon lett-e IsReference beállítva.
Name	Lekéri vagy beállítja a típushoz tartozó adatszerződés nevét.
Namespace	Lekéri vagy beállítja a típushoz tartozó adatszerződés névterét.
TypeId	Ha származtatott osztályban implementálják, ehhez egy egyedi azonosítót Attributekap. (Öröklődés forrása Attribute)

Metódusok

Name	Description
Equals(Object)	Olyan értéket ad vissza, amely jelzi, hogy ez a példány egyenlő-e egy adott objektummal. (Öröklődés forrása Attribute)
GetHashCode()	A példány kivonatkódját adja vissza. (Öröklődés forrása Attribute)
GetType()	Lekéri az Type aktuális példányt. (Öröklődés forrása Object)
IsDefaultAttribute()	Ha egy származtatott osztályban felül van bírálva, azt jelzi, hogy a példány értéke-e a származtatott osztály alapértelmezett értéke. (Öröklődés forrása Attribute)
Match(Object)	Származtatott osztály felülírásakor egy olyan értéket ad vissza, amely jelzi, hogy ez a példány egy adott objektummal egyenlő-e. (Öröklődés forrása Attribute)
MemberwiseClone()	Az aktuális Objectpéldány sekély másolatát hozza létre. (Öröklődés forrása Object)
ToString()	Az aktuális objektumot jelképező sztringet ad vissza. (Öröklődés forrása Object)

Lásd még

• IExtensibleDataObject
• ExtensionDataObject
• DataContractSerializer
• DataMemberAttribute
• ISerializable
• KnownTypeAttribute
• Adatszerződések használata