DataContractAttribute Classe

Définition

Spécifie que le type définit ou implémente un contrat de données et qu'il est sérialisable par un sérialiseur, tel que le DataContractSerializer.Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Pour rendre un type sérialisable, les auteurs de types doivent définir un contrat de données pour ce type.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
Héritage
DataContractAttribute
Attributs

Exemples

L'exemple suivant sérialise et désérialise une classe nommée Person à laquelle le DataContractAttribute a été appliqué.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Notez que les propriétés Namespace et Name ont des valeurs qui substituent les paramètres par défaut.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 

Remarques

Appliquez l'attribut DataContractAttribute aux types (classes, structures ou énumérations) qui sont utilisés dans les opérations de sérialisation et de désérialisation par le DataContractSerializer.Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. Si vous envoyez ou recevez des messages à l’aide de l’infrastructure Windows Communication Foundation (WCF), vous devez également appliquer les DataContractAttribute à toutes les classes qui contiennent et manipulent les données envoyées dans les messages.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. Pour plus d’informations sur les contrats de données, consultez utilisation de contrats de données.For more information about data contracts, see Using Data Contracts.

Vous devez également appliquer les DataMemberAttribute à tout champ, propriété ou événement qui contiennent des valeurs que vous voulez sérialiser.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. En appliquant le DataContractAttribute, vous permettez explicitement au DataContractSerializer de sérialiser et de désérialiser les données.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Attention

Vous pouvez appliquer le DataMemberAttribute aux champs privés.You can apply the DataMemberAttribute to private fields. Soyez conscient 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 que, par conséquent, elles peuvent être affichées ou interceptées par un utilisateur ou un processus malveillant.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.

Pour plus d’informations sur les contrats de données, consultez les rubriques figurant dans utilisation de contrats de données.For more information about data contracts, see the topics listed in Using Data Contracts.

Contrats de donnéesData Contracts

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.A data contract is an abstract description of a set of fields with a name and data type for each field. Le contrat de données existe en dehors de toute implémentation unique pour permettre aux services sur différentes plates-formes d'interopérer.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Tant que les données passées entre les services se conforment au même contrat, tous les services peuvent traiter les données.As long as the data passed between the services conforms to the same contract, all the services can process the data. Ce traitement est également connu sous le nom de système faiblement couplé.This processing is also known as a loosely coupled system. Un contrat de données est également semblable à une interface dans le sens où le contrat spécifie comment les données doivent être fournies afin qu'elles puissent être traitées par une application.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. Par exemple, le contrat de données peut demander un type de données nommé "Person" qui comporte deux champs de texte nommés, "FirstName" et "LastName".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Pour créer un contrat de données, appliquez simplement DataContractAttribute à la classe et DataMemberAttribute aux champs ou aux propriétés qui doivent être sérialisés.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Lorsqu'elles sont sérialisées, les données se conforment au contrat de données qui est implicitement intégré au type.When serialized, the data conforms to the data contract that is implicitly built into the type.

Notes

Un contrat de données diffère considérablement d'une interface réelle dans son comportement d'héritage.A data contract differs significantly from an actual interface in its inheritance behavior. Les interfaces sont héritées par les types dérivés.Interfaces are inherited by any derived types. Lorsque vous appliquez le DataContractAttribute à une classe de base, les types dérivés n'héritent pas de l'attribut ou du comportement.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Toutefois, si un type dérivé comporte un contrat de données, les membres de données de la classe de base sont alors sérialisés.However, if a derived type has a data contract, the data members of the base class are serialized. Toutefois, vous devez appliquer le DataMemberAttribute aux nouveaux membres dans une classe dérivée pour les rendre sérialisables.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Documents de schéma XML et outil SvcUtilXML Schema Documents and the SvcUtil Tool

Si vous échangez des données avec des services, vous devez décrire le contrat de données.If you are exchanging data with other services, you must describe the data contract. Pour la version actuelle du DataContractSerializer, un schéma XML peut être utilisé pour définir des contrats de données.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (D’autres formes de métadonnées/description peuvent être utilisées dans le même but.) Pour créer un schéma XML à partir de votre application, utilisez l' outil ServiceModel Metadata Utility Tool (Svcutil. exe) avec l’option de ligne de commande /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. Lorsque l'entrée de l'outil est un assembly, l'outil génère par défaut un jeu de schémas XML qui définissent tous les types de contrats de données trouvés dans cet 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. À l'inverse, vous pouvez également utiliser l'outil Svcutil.exe pour créer des définitions de classe Visual Basic ou C# qui se conforment aux spécifications des schémas XML utilisant des constructions que les contrats de données peuvent exprimer.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. Dans ce cas, l’option de ligne de commande /dconly n’est pas obligatoire.In this case, the /dconly command line option is not required.

Si l'entrée de l'outil Svcutil.exe est un schéma XML, l'outil crée par défaut un ensemble de classes.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Si vous examinez ces classes, vous pouvez constater que le DataContractAttribute a été appliqué.If you examine those classes, you find that the DataContractAttribute has been applied. Vous pouvez utiliser ces classes afin de créer une application pour traiter des données qui doivent être échangées avec d'autres services.You can use those classes to create a new application to process data that must be exchanged with other services.

Vous pouvez également exécuter l’outil sur un point de terminaison qui retourne un document Web Services Description Language (WSDL) pour générer automatiquement le code et la configuration afin de créer 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. Le code généré inclut des types qui sont marqués avec le DataContractAttribute.The generated code includes types that are marked with the DataContractAttribute.

Réutilisation des types existantsReusing Existing Types

Un contrat de données comporte deux spécifications de base : un nom stable et une liste de membres.A data contract has two basic requirements: a stable name and a list of members. Le nom stable est composé de l'URI (Uniform Resource Identifier) de l'espace de noms et du nom local du contrat.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. Par défaut, lorsque vous appliquez le DataContractAttribute à une classe, il utilise le nom de la classe comme nom local et l’espace de noms de la classe (préfixé avec "http://schemas.datacontract.org/2004/07/") comme URI de l’espace de noms.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. Vous pouvez substituer les valeurs par défaut en définissant les propriétés Name et Namespace.You can override the defaults by setting the Name and Namespace properties. Vous pouvez également modifier l'espace de noms en appliquant le ContractNamespaceAttribute à l'espace de noms.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Utilisez cette fonction lorsque vous avez un type existant qui traite les données exactement comme vous l'avez demandé mais qui contient un espace de noms et un nom de classe différents dans le contrat de données.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. En substituant les valeurs par défaut, vous pouvez réutiliser votre type existant et conformer les données sérialisées au contrat de données.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Notes

Dans du code, vous pouvez utiliser le mot DataContract au lieu de DataContractAttribute qui est plus long.In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Gestion de versionVersioning

Un contrat de données accepte également des versions ultérieures.A data contract can also accommodate later versions of itself. Autrement dit, lorsqu'une version ultérieure du contrat inclut des données supplémentaires, ces données sont stockées et retournées intactes à un expéditeur.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. Pour cela, implémentez l'interface IExtensibleDataObject.To do this, implement the IExtensibleDataObject interface.

Pour plus d’informations sur le contrôle de version, consultez contrôle de version des contrats de données.For more information about versioning, see Data Contract Versioning.

Constructeurs

DataContractAttribute()

Initialise une nouvelle instance de la classe DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Propriétés

IsNameSetExplicitly

Obtient l’information indiquant si Name a été défini explicitement.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Obtient l’information indiquant si Namespace a été défini explicitement.Gets whether Namespace has been explicitly set.

IsReference

Obtient ou définit une valeur qui indique s'il faut conserver les données de référence d'objet.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Obtient l’information indiquant si IsReference a été défini explicitement.Gets whether IsReference has been explicitly set.

Name

Obtient ou définit le nom du contrat de données pour le type.Gets or sets the name of the data contract for the type.

Namespace

Obtient ou définit l'espace de noms du contrat de données pour le type.Gets or sets the namespace for the data contract for the type.

TypeId

Lors de l'implémentation dans une classe dérivée, obtient un identificateur unique pour l'objet Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Hérité de Attribute)

Méthodes

Equals(Object)

Retourne une valeur qui indique si cette instance est égale à un objet spécifié.Returns a value that indicates whether this instance is equal to a specified object.

(Hérité de Attribute)
GetHashCode()

Retourne le code de hachage de cette instance.Returns the hash code for this instance.

(Hérité de Attribute)
GetType()

Obtient le Type de l'instance actuelle.Gets the Type of the current instance.

(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 pour la classe dérivée.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Hérité de Attribute)
Match(Object)

En cas de substitution dans une classe dérivée, retourne une valeur indiquant si cette instance équivaut à un objet spécifié.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Hérité de Attribute)
MemberwiseClone()

Crée une copie superficielle du Object actuel.Creates a shallow copy of the current Object.

(Hérité de Object)
ToString()

Retourne une chaîne qui représente l'objet en cours.Returns a string that represents the current object.

(Hérité de Object)

Implémentations d’interfaces explicites

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

Mappe un jeu de noms avec un jeu correspondant d'identificateurs de dispatch.Maps a set of names to a corresponding set of dispatch identifiers.

(Hérité de Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Récupère les informations de type pour un objet, qui peuvent être utilisées pour obtenir les informations de type d'une interface.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Hérité de Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Récupère le nombre d'interfaces d'informations de type fourni par un objet (0 ou 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Hérité de Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Fournit l'accès aux propriétés et aux méthodes exposées par un objet.Provides access to properties and methods exposed by an object.

(Hérité de Attribute)

S’applique à

Voir aussi