Classe DataContractAttribute (System.Runtime.Serialization)

Cambia visualizzazione:
ScriptFree
Riferimento a .NET Framework
Classe DataContractAttribute
Il presente articolo è stato tradotto manualmente. Per visualizzare questa pagina e contemporaneamente visualizzarne il contenuto in lingua inglese, passare alla visualizzazione semplificata.

Specifica che il tipo definisce o implementa un contratto dati ed è serializzabile da un serializzatore, ad esempio la classe DataContractSerializer.Per rendere serializzabile il proprio tipo, gli autori del tipo devono definire un contratto dati per tale tipo.

Gerarchia di ereditarietà

System.Object
  System.Attribute
    System.Runtime.Serialization.DataContractAttribute

Spazio dei nomi:  System.Runtime.Serialization
Assembly:  System.Runtime.Serialization (in System.Runtime.Serialization.dll)
Sintassi

Visual Basic
<AttributeUsageAttribute(AttributeTargets.Class Or AttributeTargets.Struct Or AttributeTargets.Enum, Inherited := False,  _
	AllowMultiple := False)> _
Public NotInheritable Class DataContractAttribute _
	Inherits Attribute
C#
[AttributeUsageAttribute(AttributeTargets.Class|AttributeTargets.Struct|AttributeTargets.Enum, Inherited = false, 
	AllowMultiple = false)]
public sealed class DataContractAttribute : Attribute
Visual C++
[AttributeUsageAttribute(AttributeTargets::Class|AttributeTargets::Struct|AttributeTargets::Enum, Inherited = false, 
	AllowMultiple = false)]
public ref class DataContractAttribute sealed : public Attribute
F#
[<Sealed>]
[<AttributeUsageAttribute(AttributeTargets.Class|AttributeTargets.Struct|AttributeTargets.Enum, Inherited = false, 
    AllowMultiple = false)>]
type DataContractAttribute =  
    class
        inherit Attribute
    end

Il tipo DataContractAttribute espone i seguenti membri.

Costruttori

  Nome Descrizione
Metodo pubblico ms585243.PortableClassLibrary(it-it,VS.100).gif DataContractAttribute Inizializza una nuova istanza della classe DataContractAttribute.
In alto
Proprietà

  Nome Descrizione
Proprietà pubblica ms585243.PortableClassLibrary(it-it,VS.100).gif IsReference Ottiene o imposta un valore che indica se mantenere i dati del riferimento all'oggetto.
Proprietà pubblica ms585243.PortableClassLibrary(it-it,VS.100).gif Name Ottiene o imposta il nome del contratto dati per il tipo.
Proprietà pubblica ms585243.PortableClassLibrary(it-it,VS.100).gif Namespace Ottiene o imposta lo spazio dei nomi del contratto dati per il tipo.
Proprietà pubblica TypeId Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute. (Ereditato da Attribute)
In alto
Metodi

  Nome Descrizione
Metodo pubblico ms585243.PortableClassLibrary(it-it,VS.100).gif Equals Infrastruttura. Restituisce un valore che indica se l'istanza è uguale a un oggetto specificato. (Ereditato da Attribute)
Metodo protetto ms585243.PortableClassLibrary(it-it,VS.100).gif Finalize Consente a un oggetto di provare a liberare risorse ed eseguire altre operazioni di pulitura prima che l'oggetto stesso venga recuperato dalla procedura di Garbage Collection. (Ereditato da Object)
Metodo pubblico ms585243.PortableClassLibrary(it-it,VS.100).gif GetHashCode Restituisce il codice hash per l'istanza. (Ereditato da Attribute)
Metodo pubblico ms585243.PortableClassLibrary(it-it,VS.100).gif GetType Ottiene l'oggetto Type dell'istanza corrente. (Ereditato da Object)
Metodo pubblico IsDefaultAttribute Quando è sottoposto a override in una classe derivata, indica se il valore di questa istanza è il valore predefinito della classe derivata. (Ereditato da Attribute)
Metodo pubblico Match Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato. (Ereditato da Attribute)
Metodo protetto ms585243.PortableClassLibrary(it-it,VS.100).gif MemberwiseClone Consente di creare una copia dei riferimenti dell'oggetto Object corrente. (Ereditato da Object)
Metodo pubblico ms585243.PortableClassLibrary(it-it,VS.100).gif ToString Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object)
In alto
Implementazioni esplicite dell'interfaccia

  Nome Descrizione
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetIDsOfNames Esegue il mapping di un set di nomi a un set corrispondente di ID di invio. (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetTypeInfo Recupera le informazioni sul tipo relative a un oggetto, che possono essere utilizzate per ottenere informazioni sul tipo relative a un'interfaccia. (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.GetTypeInfoCount Recupera il numero delle interfacce di informazioni di tipo fornite da un oggetto (0 o 1). (Ereditato da Attribute)
Implementazione esplicita dell'interfaccia Metodo privato _Attribute.Invoke Fornisce l'accesso a proprietà e metodi esposti da un oggetto. (Ereditato da Attribute)
In alto
Note

Applicare l'attributo DataContractAttribute a tipi (classi, strutture o enumerazioni) utilizzati in operazioni di serializzazione e deserializzazione da parte di DataContractSerializer. Se si inviano o si ricevono messaggi utilizzando l'infrastruttura , è necessario applicare DataContractAttribute alle classi che contengono e utilizzano i dati inviati nei messaggi. Per ulteriori informazioni su sui contratti dati, vedere Using Data Contracts.

È inoltre necessario applicare l'attributo DataMemberAttribute a qualsiasi campo, proprietà o evento che contiene valori che si desidera serializzare. Applicando l'attributo DataContractAttribute si consente in modo esplicito a DataContractSerializer di serializzare e deserializzare i dati.

Nota di avviso Attenzione

È possibile applicare l'attributo DataMemberAttribute a campi privati. Tenere presente che i dati restituiti dal campo (anche se privato) vengono serializzati e deserializzati e possono quindi essere visualizzati o intercettati da un utente o processo malintenzionato.

Per ulteriori informazioni su sui contratti dati, vedere gli argomenti elencati in Using Data Contracts.

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 ogni singola implementazione per consentire l'interoperabilità tra i servizi in esecuzione su piattaforme diverse. Se i dati passati tra i servizi sono conformi allo stesso contratto, tutti i servizi possono elaborare i dati. Questa elaborazione è anche nota come sistema ad accoppiamento debole (loose coupling). Un contratto dati è inoltre simile a un'interfaccia in quanto specifica la modalità di consegna dei dati affinché possano essere elaborati da un'applicazione. Il contratto dati può richiedere, ad esempio, un tipo di dati denominato "Persona" comprendente due campi di testo denominati "Nome" e "Cognome". Per creare un contratto dati, applicare DataContractAttribute alla classe e DataMemberAttribute a qualsiasi campo o proprietà che è necessario serializzare. Quando vengono serializzati, i dati sono conformi al contratto dati implicitamente compilato nel tipo.

Nota Nota

Il comportamento di ereditarietà di un contratto dati differisce in modo significativo da quello di una vera e propria interfaccia. Le interfacce vengono ereditate da qualsiasi tipo derivato. Quando si applica l'attributo DataContractAttribute a una classe di base, i tipi derivati non ereditano l'attributo o il comportamento. Se, tuttavia, a un tipo derivato è associato un contratto dati, i membri dati della classe base vengono serializzati. Perché i nuovi membri di una classe derivata possano essere serializzati, è comunque necessario applicare a tali membri l'attributo DataMemberAttribute.

Documenti dello schema XML e lo strumento SvcUtil

Se vengono scambiati dati con altri servizi, è necessario descrivere il contratto dati. Per la versione corrente di DataContractSerializer, per definire contratti dati è possibile utilizzare uno schema XML. Allo stesso scopo possono essere utilizzati altri formati di metadati/descrizione. Per creare uno schema XML dall'applicazione in uso, utilizzare lo strumento Service Model Metadata Utility Tool (Svcutil.exe) con l'opzione della riga di comando /dconly. Quando l'input allo strumento è un assembly, lo strumento genera per impostazione predefinita un set di schemi XML che definiscono tutti i tipi di contratto dati rilevati in tale assembly. Al contrario, lo strumento Svcutil.exe può anche essere utilizzato per creare definizioni di classi Visual Basic o C# conformi ai requisiti degli schemi XML che utilizzano costrutti che è possibile esprimere tramite contratti dati. In questo caso, l'opzione della riga di comando /dconly non è necessaria.

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

È inoltre 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 la creazione di un client . Il codice generato include tipi contrassegnati con l'attributo DataContractAttribute.

Riutilizzo di 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. Quando viene applicato a una classe, l'attributo DataContractAttribute utilizza per impostazione predefinita il nome della classe come nome locale e lo spazio dei nomi della classe (preceduto dal prefisso "http://schemas.datacontract.org/2004/07/") come URI dello spazio dei nomi. È possibile eseguire l'override dei valori predefiniti impostando le proprietà Name e Namespace. È inoltre possibile modificare lo spazio dei nomi applicandovi l'attributo ContractNamespaceAttribute. Utilizzare questa funzionalità quando si dispone di un tipo esistente che elabora i dati nel modo richiesto, ma che ha uno spazio dei nomi e un nome di classe differenti dal contratto dati. L'override dei valori predefiniti consente di riutilizzare il tipo esistente e di rendere i dati serializzati conformi al contratto dati.

Nota Nota

In qualsiasi codice è possibile utilizzare DataContract anziché la forma estesa DataContractAttribute.

Controllo delle versioni

Un contratto dati può inoltre contenere versioni successive di se stesso. Ovvero, quando una versione più recente del contratto include dati aggiuntivi, tali dati vengono archiviati e restituiti a un mittente invariati. A tal scopo, implementare l'interfaccia IExtensibleDataObject.

Per ulteriori informazioni su sul controllo delle versioni, vedere Data Contract Versioning.

Esempi

Nell'esempio seguente vengono illustrate la serializzazione e la deserializzazione di una classe denominata Person alla quale è stato applicato l'attributo DataContractAttribute. Si noti che le proprietà Namespace e Name sono state impostate su valori che determinano l'override delle impostazioni predefinite.

Visual Basic

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 


C#

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();
        }

    }
}


Informazioni sulla versione

.NET Framework

Supportato in: 4, 3.5, 3.0

.NET Framework Client Profile

Supportato in: 4, 3.5 SP1

Supportato in:
Piattaforme

Windows 7, Windows Vista SP1 o versione successiva, Windows XP SP3, Windows Server 2008 (componenti di base del server non supportati), Windows Server 2008 R2 (componenti di base del server supportati con SP1 o versione successiva), Windows Server 2003 SP2

.NET Framework non supporta tutte le versioni di ciascuna piattaforma. Per un elenco delle versioni supportate, vedere Requisiti di sistema di .NET Framework.
Codice thread safe

Qualsiasi membro static (Shared in Visual Basic) pubblico di questo tipo è thread-safe. I membri di istanza non sono garantiti come thread-safe.
Vedere anche

Riferimenti