DataContractAttribute Classe

Definizione

Specifica che il tipo definisce o implementa un contratto dati ed è serializzabile da un serializzatore, ad esempio la classe DataContractSerializer.Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Per rendere serializzabile il proprio tipo, gli autori del tipo devono definire un contratto dati per tale tipo.To make their type serializable, type authors must define a data contract for their type.

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
type DataContractAttribute = class
    inherit Attribute
Public NotInheritable Class DataContractAttribute
Inherits Attribute
Ereditarietà
DataContractAttribute
Attributi

Esempi

Nell'esempio seguente vengono illustrate la serializzazione e la deserializzazione di una classe denominata Person alla quale è stato applicato l'attributo DataContractAttribute.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Le proprietà Namespace e Name sono state impostate su valori che eseguono l'override delle impostazioni predefinite.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 

Commenti

Applicare l'attributo DataContractAttribute a tipi (classi, strutture o enumerazioni) utilizzati in operazioni di serializzazione e deserializzazione da parte di DataContractSerializer.Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. Se si inviano o si ricevono messaggi utilizzando l'infrastruttura Windows Communication Foundation (WCF), è necessario applicare DataContractAttribute anche a qualsiasi classe che contenga e modifichi i dati inviati nei messaggi.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. Per ulteriori informazioni sui contratti dati, vedere utilizzo di contratti dati.For more information about data contracts, see Using Data Contracts.

È inoltre necessario applicare l'attributo DataMemberAttribute a qualsiasi campo, proprietà o evento che contiene valori che si desidera serializzare.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Applicando l'attributo DataContractAttribute si consente in modo esplicito a DataContractSerializer di serializzare e deserializzare i dati.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Attenzione

È possibile applicare l'attributo DataMemberAttribute a campi privati.You can apply the DataMemberAttribute to private fields. 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.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.

Per ulteriori informazioni sui contratti dati, vedere gli argomenti elencati in utilizzo di contratti dati.For more information about data contracts, see the topics listed in Using Data Contracts.

Contratti datiData Contracts

Un contratto dati è una descrizione astratta di un set di campi con un nome e un tipo di dati per ogni campo.A data contract is an abstract description of a set of fields with a name and data type for each field. Il contratto dati esiste al di fuori di ogni singola implementazione per consentire l'interoperabilità tra i servizi in esecuzione su piattaforme diverse.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Se i dati passati tra i servizi sono conformi allo stesso contratto, tutti i servizi possono elaborare i dati.As long as the data passed between the services conforms to the same contract, all the services can process the data. Questa elaborazione è nota anche come sistema a regimedi controllo libero.This processing is also known as a loosely coupled system. Un contratto dati è inoltre simile a un'interfaccia in quanto specifica la modalità di consegna dei dati affinché possano essere elaborati da un'applicazione.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. Il contratto dati può richiedere, ad esempio, un tipo di dati denominato "Persona" comprendente due campi di testo denominati "Nome" e "Cognome".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Per creare un contratto dati, applicare DataContractAttribute alla classe e DataMemberAttribute a qualsiasi campo o proprietà che è necessario serializzare.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Quando vengono serializzati, i dati sono conformi al contratto dati implicitamente compilato nel tipo.When serialized, the data conforms to the data contract that is implicitly built into the type.

Nota

Il comportamento di ereditarietà di un contratto dati differisce in modo significativo da quello di una vera e propria interfaccia.A data contract differs significantly from an actual interface in its inheritance behavior. Le interfacce vengono ereditate da qualsiasi tipo derivato.Interfaces are inherited by any derived types. Quando si applica l'attributo DataContractAttribute a una classe di base, i tipi derivati non ereditano l'attributo o il comportamento.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Se, tuttavia, a un tipo derivato è associato un contratto dati, i membri dati della classe base vengono serializzati.However, if a derived type has a data contract, the data members of the base class are serialized. Perché i nuovi membri di una classe derivata possano essere serializzati, è comunque necessario applicare a tali membri l'attributo DataMemberAttribute.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Documenti dello schema XML e lo strumento SvcUtilXML Schema Documents and the SvcUtil Tool

Se vengono scambiati dati con altri servizi, è necessario descrivere il contratto dati.If you are exchanging data with other services, you must describe the data contract. Per la versione corrente di DataContractSerializer, per definire contratti dati è possibile utilizzare uno schema XML.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. Allo stesso scopo possono essere utilizzati altri formati di metadati/descrizione. Per creare un XML Schema dall'applicazione, utilizzare lo strumento ServiceModel Metadata Utility Tool (Svcutil. exe) con l'opzione della riga di comando /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. 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.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. 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.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. In questo caso, l'opzione della riga di comando /dconly non è obbligatoria.In this case, the /dconly command line option is not required.

Se l'input dello strumento Svcutil.exe è uno schema XML, per impostazione predefinita lo strumento crea un set di classi.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Se si esaminano queste classi, è possibile notare che è stato applicato l'attributo DataContractAttribute.If you examine those classes, you find that the DataContractAttribute has been applied. È possibile utilizzare queste classi per creare una nuova applicazione per elaborare dati che devono essere scambiati con altri servizi.You can use those classes to create a new application to process data that must be exchanged with other services.

È inoltre possibile eseguire lo strumento su un endpoint che restituisce un documento di Web Services Description Language (WSDL) per generare automaticamente il codice e la configurazione per la creazione di un client 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. Il codice generato include tipi contrassegnati con l'attributo DataContractAttribute.The generated code includes types that are marked with the DataContractAttribute.

Riutilizzo di tipi esistentiReusing Existing Types

Un contratto dati ha due requisiti di base: un nome stabile e un elenco di membri.A data contract has two basic requirements: a stable name and a list of members. Il nome stabile è costituito dall'URI (Uniform Resource Identifier) dello spazio dei nomi e dal nome locale del contratto.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. Per impostazione predefinita, quando si applica DataContractAttribute a una classe, il nome della classe viene utilizzato come nome locale e lo spazio dei nomi della classe (con "http://schemas.datacontract.org/2004/07/"prefisso) come URI dello spazio dei nomi.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. È possibile eseguire l'override dei valori predefiniti impostando le proprietà Name e Namespace.You can override the defaults by setting the Name and Namespace properties. È inoltre possibile modificare lo spazio dei nomi applicandovi l'attributo ContractNamespaceAttribute.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. 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.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. L'override dei valori predefiniti consente di riutilizzare il tipo esistente e di rendere i dati serializzati conformi al contratto dati.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Nota

In qualsiasi codice è possibile utilizzare DataContract anziché la forma più estesa DataContractAttribute.In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Controllo delle versioniVersioning

Un contratto dati può anche contenere versioni successive dello stesso.A data contract can also accommodate later versions of itself. Ovvero, quando una versione più recente del contratto include dati aggiuntivi, tali dati vengono archiviati e restituiti a un mittente invariati.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. A tal scopo, implementare l'interfaccia IExtensibleDataObject.To do this, implement the IExtensibleDataObject interface.

Per ulteriori informazioni sul controllo delle versioni, vedere controllo delle versioni del contratto dati.For more information about versioning, see Data Contract Versioning.

Costruttori

DataContractAttribute()

Inizializza una nuova istanza della classe DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Proprietà

IsNameSetExplicitly

Ottiene un valore che indica se Name è stato impostato in modo esplicito.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Ottiene un valore che indica se Namespace è stato impostato in modo esplicito.Gets whether Namespace has been explicitly set.

IsReference

Ottiene o imposta un valore che indica se mantenere i dati del riferimento all'oggetto.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Ottiene un valore che indica se IsReference è stato impostato in modo esplicito.Gets whether IsReference has been explicitly set.

Name

Ottiene o imposta il nome del contratto dati per il tipo.Gets or sets the name of the data contract for the type.

Namespace

Ottiene o imposta lo spazio dei nomi del contratto dati per il tipo.Gets or sets the namespace for the data contract for the type.

TypeId

Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Ereditato da Attribute)

Metodi

Equals(Object)

Restituisce un valore che indica se questa istanza è uguale a un oggetto specificato.Returns a value that indicates whether this instance is equal to a specified object.

(Ereditato da Attribute)
GetHashCode()

Restituisce il codice hash per l'istanza.Returns the hash code for this instance.

(Ereditato da Attribute)
GetType()

Ottiene l'oggetto Type dell'istanza corrente.Gets the Type of the current instance.

(Ereditato da Object)
IsDefaultAttribute()

In caso di override in una classe derivata, indica se il valore di questa istanza è il valore predefinito per la classe derivata.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Ereditato da Attribute)
Match(Object)

Quando è sottoposto a override in una classe derivata, restituisce un valore che indica se questa istanza equivale a un oggetto specificato.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Ereditato da Attribute)
MemberwiseClone()

Crea una copia superficiale dell'oggetto Object corrente.Creates a shallow copy of the current Object.

(Ereditato da Object)
ToString()

Restituisce una stringa che rappresenta l'oggetto corrente.Returns a string that represents the current object.

(Ereditato da Object)

Implementazioni dell'interfaccia esplicita

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

Esegue il mapping di un set di nomi a un set corrispondente di ID dispatch.Maps a set of names to a corresponding set of dispatch identifiers.

(Ereditato da Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Recupera le informazioni sul tipo relative a un oggetto, che possono essere usate per ottenere informazioni sul tipo relative a un'interfaccia.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Ereditato da Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Recupera il numero delle interfacce di informazioni sul tipo fornite da un oggetto (0 o 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Ereditato da Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Fornisce l'accesso a proprietà e metodi esposti da un oggetto.Provides access to properties and methods exposed by an object.

(Ereditato da Attribute)

Si applica a

Vedi anche