DataContractAttribute Classe

Définition

Espace de noms:

System.Runtime.Serialization

Assemblys:

netstandard.dll, System.Runtime.Serialization.Primitives.dll

Source:

DataContractAttribute.cs

Spécifie que le type définit ou implémente un contrat de données et est sérialisable par un sérialiseur, tel que le DataContractSerializer. Pour rendre leur type sérialisable, les auteurs de types doivent définir un contrat de données pour leur 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

[<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

Héritage

Object

Attribute

DataContractAttribute

Attributs

AttributeUsageAttribute

Exemples

L’exemple suivant sérialise et désérialise une classe nommée Person à laquelle l’application DataContractAttribute a été appliquée. Notez que les propriétés et Namespace les Name propriétés ont été définies sur des valeurs qui remplacent les paramètres par défaut.

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

Remarques

Appliquez l’attribut DataContractAttribute aux types (classes, structures ou énumérations) utilisés dans les opérations de sérialisation et de désérialisation par le DataContractSerializer. Si vous envoyez ou recevez des messages à l’aide de l’infrastructure Windows Communication Foundation (WCF), vous devez également appliquer le DataContractAttribute aux classes qui contiennent et manipulent les données dans les messages envoyés. Pour plus d’informations sur les contrats de données, consultez Utilisation de contrats de données.

Vous devez également appliquer le DataMemberAttribute à tout champ, propriété ou événement qui contient des valeurs que vous souhaitez sérialiser. En appliquant le DataContractAttribute, vous activez explicitement la DataContractSerializer sérialisation et la désérialisation des données.

Avertissement

Vous pouvez appliquer DataMemberAttribute au champ privé. N’oubliez pas que les données retournées par le champ (même s’il est privé) sont sérialisées et désérialisées, et peuvent ainsi être consultées ou interceptées par un utilisateur ou un processus malveillant.

Pour plus d’informations sur les contrats de données, consultez les rubriques répertoriées dans Utilisation des contrats de données.

Contrats de données

Un contrat de données est une description abstraite d’un ensemble de champs avec un nom et un type de données pour chaque champ. Le contrat de données existe en dehors de toute implémentation unique pour permettre aux services sur différentes plateformes d’interagir. Tant que les données transmises entre les services sont conformes au même contrat, tous les services peuvent traiter les données. Ce traitement est également appelé système faiblement couplé. Un contrat de données est également similaire à une interface dans laquelle le contrat spécifie la façon dont les données doivent être remises afin qu’elles puissent être traitées par une application. Par exemple, le contrat de données peut appeler un type de données nommé « Person » qui a deux champs de texte, nommés « FirstName » et « LastName ». Pour créer un contrat de données, appliquez le DataContractAttribute à la classe et appliquez le DataMemberAttribute à tous les champs ou propriétés qui doivent être sérialisés. En cas de sérialisation, les données sont conformes au contrat de données qui est implicitement intégré au type.

Note

Un contrat de données diffère considérablement d’une interface réelle dans son comportement d’héritage. Les interfaces sont héritées par tous les types dérivés. Lorsque vous appliquez le DataContractAttribute à une classe de base, les types dérivés n’héritent pas de l’attribut ou du comportement. Toutefois, si un type dérivé a un contrat de données, les membres de données de la classe de base sont sérialisés. Toutefois, vous devez appliquer DataMemberAttribute aux nouveaux membres dans une classe dérivée pour qu'ils deviennent sérialisables.

Documents de schéma XML et outil SvcUtil

Si vous échangez des données avec d’autres services, vous devez décrire le contrat de données. Pour la version actuelle du DataContractSerializer, un schéma XML peut être utilisé pour définir des contrats de données. (D’autres formes de métadonnées/description peuvent être utilisées à la même fin.) Pour créer un schéma XML à partir de votre application, utilisez l’outil utilitaire de métadonnées ServiceModel (Svcutil.exe) avec l’option de ligne de commande /dconly . Lorsque l’entrée de l’outil est un assembly, par défaut, l’outil génère un ensemble de schémas XML qui définissent tous les types de contrat de données trouvés dans cet assembly. À l’inverse, vous pouvez également utiliser l’outil Svcutil.exe pour créer des définitions de classes Visual Basic ou C# conformes aux exigences des schémas XML qui utilisent des constructions qui peuvent être exprimées par des contrats de données. Dans ce cas, l’option de ligne de commande /dconly n’est pas requise.

Si l’entrée de l’outil Svcutil.exe est un schéma XML, par défaut, l’outil crée un ensemble de classes. Si vous examinez ces classes, vous remarquez que le DataContractAttribute a été appliqué. Vous pouvez utiliser ces classes pour créer une application pour traiter les données qui doivent être échangées avec d’autres services.

Vous pouvez également exécuter l’outil sur un point de terminaison qui retourne un document WSDL (Web Services Description Language) pour générer automatiquement le code et la configuration pour créer un client Windows Communication Foundation (WCF). Le code généré inclut des types marqués avec le DataContractAttribute.

Réutiliser les types existants

Un contrat de données a deux exigences de base : un nom stable et une liste de membres. Le nom stable se compose de l’URI (Uniform Resource Identifier) de l’espace de noms et du nom local du contrat. Par défaut, lorsque vous appliquez la DataContractAttribute classe à une classe, elle utilise le nom de la classe comme nom local et l’espace de noms de la classe (précédé de "http://schemas.datacontract.org/2004/07/") comme URI d’espace de noms. Vous pouvez remplacer les valeurs par défaut en définissant les propriétés Name et Namespace. Vous pouvez également modifier l’espace de noms en appliquant le ContractNamespaceAttribute à celui-ci. Utilisez cette fonctionnalité lorsque vous disposez d’un type existant qui traite les données exactement comme vous le souhaitez, mais possède un autre espace de noms et un nom de classe à partir du contrat de données. En remplaçant les valeurs par défaut, vous pouvez réutiliser votre type existant et avoir les données sérialisées conformes au contrat de données.

Note

Dans n’importe quel code, vous pouvez utiliser le mot DataContract au lieu du plus long DataContractAttribute.

Gestion des versions

Un contrat de données peut également prendre en charge les versions ultérieures de lui-même. Autrement dit, lorsqu’une version ultérieure du contrat inclut des données supplémentaires, ces données sont stockées et retournées à un expéditeur non touché. Pour ce faire, implémentez l’interface IExtensibleDataObject .

Pour plus d’informations sur le contrôle de version, consultez Gestion des versions de contrat de données.

Constructeurs

Nom	Description
DataContractAttribute()	Initialise une nouvelle instance de la classe DataContractAttribute.

Propriétés

Nom	Description
IsNameSetExplicitly	Obtient si Name elle a été définie explicitement.
IsNamespaceSetExplicitly	Obtient si Namespace elle a été définie explicitement.
IsReference	Obtient ou définit une valeur qui indique s'il faut conserver les données de référence d'objet.
IsReferenceSetExplicitly	Obtient si IsReference elle a été définie explicitement.
Name	Obtient ou définit le nom du contrat de données pour le type.
Namespace	Obtient ou définit l'espace de noms du contrat de données associé au type.
TypeId	En cas d’implémentation dans une classe dérivée, obtient un identificateur unique pour cette Attribute. (Hérité de Attribute)

Méthodes

Nom	Description
Equals(Object)	Retourne une valeur qui indique si cette instance est égale à un objet spécifié. (Hérité de Attribute)
GetHashCode()	Retourne le code de hachage pour cette instance. (Hérité de Attribute)
GetType()	Obtient la Type de l’instance actuelle. (Hérité de Object)
IsDefaultAttribute()	En cas de substitution dans une classe dérivée, indique si la valeur de cette instance est la valeur par défaut de la classe dérivée. (Hérité de Attribute)
Match(Object)	En cas de substitution dans une classe dérivée, retourne une valeur qui indique si cette instance est égale à un objet spécifié. (Hérité de Attribute)
MemberwiseClone()	Crée une copie superficielle du Objectactuel. (Hérité de Object)
ToString()	Retourne une chaîne qui représente l’objet actuel. (Hérité de Object)

Voir aussi

• IExtensibleDataObject
• ExtensionDataObject
• DataContractSerializer
• DataMemberAttribute
• ISerializable
• KnownTypeAttribute
• Utilisation de contrats de données