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.
System.Attribute
System.Runtime.Serialization.DataContractAttribute
Spazio dei nomi: System.Runtime.Serialization
Assembly: System.Runtime.Serialization (in System.Runtime.Serialization.dll)
<AttributeUsageAttribute(AttributeTargets.Class Or AttributeTargets.Struct Or AttributeTargets.Enum, Inherited := False, _ AllowMultiple := False)> _ Public NotInheritable Class DataContractAttribute _ Inherits Attribute
[AttributeUsageAttribute(AttributeTargets.Class|AttributeTargets.Struct|AttributeTargets.Enum, Inherited = false, AllowMultiple = false)] public sealed class DataContractAttribute : Attribute
[AttributeUsageAttribute(AttributeTargets::Class|AttributeTargets::Struct|AttributeTargets::Enum, Inherited = false, AllowMultiple = false)] public ref class DataContractAttribute sealed : public Attribute
[<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.
| Nome | Descrizione | |
|---|---|---|
|
DataContractAttribute | Inizializza una nuova istanza della classe DataContractAttribute. |
| Nome | Descrizione | |
|---|---|---|
|
IsReference | Ottiene o imposta un valore che indica se mantenere i dati del riferimento all'oggetto. |
|
Name | Ottiene o imposta il nome del contratto dati per il tipo. |
|
Namespace | Ottiene o imposta lo spazio dei nomi del contratto dati per il tipo. |
|
TypeId | Quando è implementata in una classe derivata, ottiene un identificatore univoco della classe Attribute. (Ereditato da Attribute) |
| Nome | Descrizione | |
|---|---|---|
|
Equals | Infrastruttura. Restituisce un valore che indica se l'istanza è uguale a un oggetto specificato. (Ereditato da Attribute) |
|
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) |
|
GetHashCode | Restituisce il codice hash per l'istanza. (Ereditato da Attribute) |
|
GetType | Ottiene l'oggetto Type dell'istanza corrente. (Ereditato da Object) |
|
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) |
|
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) |
|
MemberwiseClone | Consente di creare una copia dei riferimenti dell'oggetto Object corrente. (Ereditato da Object) |
|
ToString | Restituisce una stringa che rappresenta l'oggetto corrente. (Ereditato da Object) |
| Nome | Descrizione | |
|---|---|---|
|
_Attribute.GetIDsOfNames | Esegue il mapping di un set di nomi a un set corrispondente di ID di invio. (Ereditato da Attribute) |
|
_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) |
|
_Attribute.GetTypeInfoCount | Recupera il numero delle interfacce di informazioni di tipo fornite da un oggetto (0 o 1). (Ereditato da Attribute) |
|
_Attribute.Invoke | Fornisce l'accesso a proprietà e metodi esposti da un oggetto. (Ereditato da Attribute) |
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.
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
|
|---|
|
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
|
|---|
|
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.
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.
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
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(); } } }
.NET Framework
Supportato in: 4, 3.5, 3.0.NET Framework Client Profile
Supportato in: 4, 3.5 SP1Supportato in:
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.
Attenzione
Nota