DataContractAttribute Classe

Definizione

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

Ereditarietà

Object

Attribute

DataContractAttribute

Attributi

AttributeUsageAttribute

Esempio

Nell'esempio seguente serializza e deserializza una classe denominata Person a cui è stato applicato l'oggetto DataContractAttribute . Si noti che le Namespace proprietà e Name sono state impostate su valori che eseguono l'override delle impostazioni predefinite.

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

Commenti

Applicare l'attributo DataContractAttribute ai tipi (classi, strutture o enumerazioni) utilizzati nelle operazioni di serializzazione e deserializzazione da parte di DataContractSerializer. Se si inviano o si ricevono messaggi usando l'infrastruttura windows Communication Foundation (WCF), è necessario applicare anche a DataContractAttribute tutte le classi che contengono e modificano i dati inviati nei messaggi. Per altre informazioni sui contratti dati, vedere Uso di contratti dati.

È inoltre necessario applicare l'oggetto DataMemberAttribute a qualsiasi campo, proprietà o evento che contiene valori da serializzare. Applicando il DataContractAttribute, si abilita in modo esplicito il DataContractSerializer a serializzare e deserializzare i dati.

Per altre informazioni sui contratti dati, vedere gli argomenti elencati in Uso di contratti dati.

Contratti dati

Un contratto dati è una descrizione astratta di un set di campi con un nome e un tipo di dati per ogni campo. Il contratto dati esiste al di fuori di qualsiasi singola implementazione per consentire l'interoperabilità dei servizi su piattaforme diverse. Se i dati passati tra i servizi sono conformi allo stesso contratto, tutti i servizi possono elaborare i dati. Questa elaborazione è nota anche come sistema ad accoppiamento libero. Un contratto dati è anche simile a un'interfaccia in quanto il contratto specifica il modo in cui i dati devono essere recapitati in modo che possano essere elaborati da un'applicazione. Ad esempio, il contratto dati può richiedere un tipo di dati denominato "Person" con due campi di testo, denominato "FirstName" e "LastName". Per creare un contratto dati, applicare DataContractAttribute alla classe e DataMemberAttribute a tutti i campi o alle proprietà che devono essere serializzati. In caso di serializzazione, i dati sono conformi al contratto dati integrato in modo implicito nel tipo .

Documenti di XML Schema e lo strumento SvcUtil

Se si scambiano dati con altri servizi, è necessario descrivere il contratto dati. Per la versione corrente di DataContractSerializer, è possibile usare un XML Schema per definire i contratti dati. Altri tipi di metadati/descrizione possono essere usati per lo stesso scopo. Per creare uno schema XML dall'applicazione, usare lo strumento utilità metadati ServiceModel (Svcutil.exe) con l'opzione della riga di comando /dconly . Quando l'input dello strumento è un assembly, per impostazione predefinita, lo strumento genera un set di XML Schema che definiscono tutti i tipi di contratto dati trovati in tale assembly. Al contrario, è anche possibile usare lo strumento Svcutil.exe per creare definizioni di classi Visual Basic o C# conformi ai requisiti di XML Schema che usano costrutti che possono essere espressi dai contratti dati. In questo caso, l'opzione della riga di comando /dconly non è obbligatoria.

Se l'input dello strumento Svcutil.exe è uno schema XML, per impostazione predefinita, lo strumento crea un set di classi. Se si esaminano le classi, si scopre che il DataContractAttribute è stato applicato. È possibile usare queste classi per creare una nuova applicazione per elaborare i dati che devono essere scambiati con altri servizi.

È anche possibile eseguire lo strumento su un endpoint che restituisce un documento WSDL (Web Services Description Language) per generare automaticamente il codice e la configurazione per creare un client Windows Communication Foundation (WCF). Il codice generato include tipi contrassegnati con .DataContractAttribute

Riutilizzare i tipi esistenti

Un contratto dati ha due requisiti di base: un nome stabile e un elenco di membri. Il nome stabile è costituito dall'URI (Uniform Resource Identifier) dello spazio dei nomi e dal nome locale del contratto. Per impostazione predefinita, quando si applica a DataContractAttribute una classe, usa il nome della classe come nome locale e lo spazio dei nomi della classe (preceduto da "http://schemas.datacontract.org/2004/07/") come URI dello spazio dei nomi. È possibile eseguire l'override delle impostazioni predefinite impostando le Name proprietà e Namespace . È anche possibile modificare lo spazio dei nomi applicando ContractNamespaceAttribute allo spazio dei nomi. Usare questa funzionalità quando si dispone di un tipo esistente che elabora i dati esattamente come richiesto, ma ha uno spazio dei nomi e un nome di classe diversi dal contratto dati. Eseguendo l'override dei valori predefiniti, è possibile riutilizzare il tipo esistente e avere i dati serializzati conformi al contratto dati.

Versionamento

Un contratto dati può anche contenere versioni successive di se stesso. Ovvero, quando una versione successiva del contratto include dati aggiuntivi, tali dati vengono archiviati e restituiti a un mittente non interessato. A tale scopo, implementare l'interfaccia IExtensibleDataObject .

Per altre informazioni sul controllo delle versioni, vedere Controllo delle versioni del contratto dati.

Vedi anche

• IExtensibleDataObject
• ExtensionDataObject
• DataContractSerializer
• DataMemberAttribute
• ISerializable
• KnownTypeAttribute
• Uso di contratti di dati