Classe System.Runtime.Serialization.DataContractAttribute

Questo articolo fornisce osservazioni supplementari alla documentazione di riferimento per questa API.

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 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'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 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 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 è nota anche come sistema ad accoppiamento libero. 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 di XML Schema 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. 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 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 è obbligatoria.

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.

È 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 l'attributo 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 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 più estesa DataContractAttribute.

Controllo delle versioni

Un contratto dati può anche contenere versioni successive dello 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 altre informazioni sul controllo delle versioni, vedere Controllo delle versioni del contratto dati.