DataContractAttribute Clase

Definición

Especifica que el tipo define o implementa un contrato de datos y los puede serializar un serializador como, por ejemplo DataContractSerializer.Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Para que hacer su tipo sea serializable, los autores del tipo deben definir un contrato de datos para dicho 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
Herencia
DataContractAttribute
Atributos

Ejemplos

En el siguiente ejemplo, se serializa y deserializa una clase denominada Person a la que se ha aplicado DataContractAttribute.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Observe que Namespace y las propiedades Name se han establecido en los valores que reemplazan la configuración predeterminada.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 

Comentarios

Aplique el atributo DataContractAttribute a los tipos (clases, estructuras o enumeraciones) que usa DataContractSerializer en serialización y operaciones de la deserializaciónApply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. Si envía o recibe mensajes mediante la infraestructura de Windows Communication Foundation (WCF), también debe aplicar DataContractAttribute a cualquier clase que contenga y manipule datos enviados en mensajes.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. Para obtener más información sobre los contratos de datos, consulte uso de contratos de datos.For more information about data contracts, see Using Data Contracts.

También se debe aplicar DataMemberAttribute a cualquier campo, propiedad o evento que contenga los valores que desee serializar.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Si se aplica DataContractAttribute, se permite explícitamente DataContractSerializer serializar y deserializar los datos.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Precaución

Puede aplicar DataMemberAttribute a campos privados.You can apply the DataMemberAttribute to private fields. Tenga en cuenta que los datos devueltos por el campo (aun cuando es privado) se serializan y deserializan, de modo que un usuario o proceso malintencionado puede verlos o interceptarlos.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.

Para obtener más información sobre los contratos de datos, consulte los temas que se enumeran en uso de contratos de datos.For more information about data contracts, see the topics listed in Using Data Contracts.

Contratos de datosData Contracts

Un contrato de datos es una descripción abstracta de un conjunto de campos con un nombre y un tipo de datos para cada campo.A data contract is an abstract description of a set of fields with a name and data type for each field. El contrato de datos existe fuera de cualquier implementación única para permitir la interoperación de servicios en plataformas diferentes.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Siempre y cuando los datos que se pasen entre los servicios se ajusten al mismo contrato, todos los servicios podrán procesar los datos.As long as the data passed between the services conforms to the same contract, all the services can process the data. Este procesamiento también se conoce como sistema de acoplamiento flexible.This processing is also known as a loosely coupled system. Un contrato de datos también es similar a una interfaz en la que el contrato especifica cómo se deben entregar los datos para que los pueda procesar una aplicación.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. Por ejemplo, el contrato de datos puede llamar a un tipo de datos denominado "Persona" que tiene dos campos de texto, denominados "Nombre" y "Apellidos".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Para crear un contrato de datos, aplique DataContractAttribute a la clase y aplique DataMemberAttribute a cualquier campo o propiedad que se deba serializar.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Cuando esté serializado, los datos se ajustarán al contrato de datos que está integrado implícitamente en el tipo.When serialized, the data conforms to the data contract that is implicitly built into the type.

Nota

Un contrato de datos difiere significativamente de una interfaz real en su comportamiento con las herencias.A data contract differs significantly from an actual interface in its inheritance behavior. Las interfaces se heredan mediante cualquiera de los tipos derivados.Interfaces are inherited by any derived types. Al aplicar DataContractAttribute a una clase base, los tipos derivados no heredan el atributo ni el comportamiento.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. Sin embargo, si un tipo derivado tiene un contrato de datos, se serializan los miembros de datos de la clase base.However, if a derived type has a data contract, the data members of the base class are serialized. No obstante, debe aplicar DataMemberAttribute a los nuevos miembros en una clase derivada para que se puedan serializar.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Documentos de esquema XML y la herramienta SvcUtilXML Schema Documents and the SvcUtil Tool

Si está intercambiando datos con otros servicios, debe describir el contrato de datos.If you are exchanging data with other services, you must describe the data contract. Para la versión actual de DataContractSerializer, se puede usar un esquema XML para definir los contratos de datos.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (También se podrían usar otras formas de metadatos/descripción con la misma finalidad.) Para crear un esquema XML desde la aplicación, use la herramienta de utilidad de metadatos de ServiceModel (SvcUtil. exe) con la opción de línea de comandos /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. Cuando la entrada a la herramienta es un ensamblado, de forma predeterminada, la herramienta genera un conjunto de esquemas XML que define todos los tipos de contrato de datos situados en ese ensamblado.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. A la inversa, también puede usar la herramienta Svcutil.exe para crear definiciones de clase de Visual Basic o de C# que se ajusten a los requisitos de esquemas XML que usan estructuras que pueden expresarse mediante contratos de datos.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. En este caso, no es necesaria la opción de línea de comandos /dconly .In this case, the /dconly command line option is not required.

Si la entrada a la herramienta Svcutil.exe es un esquema XML, de forma predeterminada, la herramienta crea un conjunto de clases.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Si examina esas clases, observará que se ha aplicado DataContractAttribute.If you examine those classes, you find that the DataContractAttribute has been applied. Puede usar esas clases para crear una nueva aplicación para procesar datos que se deben intercambiar con otros servicios.You can use those classes to create a new application to process data that must be exchanged with other services.

También puede ejecutar la herramienta con un punto de conexión que devuelva un documento de lenguaje de descripción de servicios web (WSDL) para generar automáticamente el código y la configuración para crear un cliente de 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. Los tipos de inclusiones de código generados que se marcan con DataContractAttribute.The generated code includes types that are marked with the DataContractAttribute.

Reutilizar tipos existentesReusing Existing Types

Un contrato de datos tiene dos requisitos básicos: un nombre estable y una lista de miembros.A data contract has two basic requirements: a stable name and a list of members. El nombre estable consta del identificador uniforme de recursos (URI) para el espacio de nombres y el nombre local del contrato.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. De forma predeterminada, cuando se aplica DataContractAttribute a una clase, utiliza el nombre de clase como el nombre local y el espacio de nombres de la clase ( "http://schemas.datacontract.org/2004/07/"con el prefijo) como el identificador URI del espacio de nombres.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. Los valores predeterminados se pueden invalidar estableciendo las propiedades Name y Namespace.You can override the defaults by setting the Name and Namespace properties. También se puede cambiar el espacio de nombres aplicando ContractNamespaceAttribute al espacio de nombres.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Use esta función cuando tenga un tipo existente que procese datos exactamente como los necesita pero que tienen un espacio de nombres y un nombre de clase diferentes a los del contrato de datos.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. Mediante la invalidación de los valores predeterminados, puede reutilizar el tipo existente y hacer que los datos serializados se ajusten al contrato de datos.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Nota

En cualquier código, puede usar la palabra DataContract en lugar de la forma más larga DataContractAttribute.In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Control de versionesVersioning

Un contrato de datos también puede alojar versiones posteriores de sí mismo.A data contract can also accommodate later versions of itself. Es decir, cuando una versión posterior del contrato incluye datos adicionales, esos datos se almacenan y se devuelven a un remitente intactos.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. Para ello, implemente la interfaz IExtensibleDataObject.To do this, implement the IExtensibleDataObject interface.

Para obtener más información sobre el control de versiones, vea control de versiones de contratos de datos.For more information about versioning, see Data Contract Versioning.

Constructores

DataContractAttribute()

Inicializa una nueva instancia de la clase DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Propiedades

IsNameSetExplicitly

Obtiene si Name se estableció explícitamente.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Obtiene si Namespace se estableció explícitamente.Gets whether Namespace has been explicitly set.

IsReference

Obtiene o establece un valor que indica si conservar los datos de referencia al objeto.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Obtiene si IsReference se estableció explícitamente.Gets whether IsReference has been explicitly set.

Name

Obtiene o establece el nombre del contrato de datos para el tipo.Gets or sets the name of the data contract for the type.

Namespace

Obtiene o establece el espacio de nombres del contrato de datos para el tipo.Gets or sets the namespace for the data contract for the type.

TypeId

Cuando se implementa en una clase derivada, obtiene un identificador único para este Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Heredado de Attribute)

Métodos

Equals(Object)

Devuelve un valor que indica si esta instancia es igual que un objeto especificado.Returns a value that indicates whether this instance is equal to a specified object.

(Heredado de Attribute)
GetHashCode()

Devuelve el código hash de esta instancia.Returns the hash code for this instance.

(Heredado de Attribute)
GetType()

Obtiene el Type de la instancia actual.Gets the Type of the current instance.

(Heredado de Object)
IsDefaultAttribute()

Si se reemplaza en una clase derivada, indica si el valor de esta instancia es el valor predeterminado de la clase derivada.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Heredado de Attribute)
Match(Object)

Cuando se invalida en una clase derivada, devuelve un valor que indica si esta instancia es igual a un objeto especificado.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Heredado de Attribute)
MemberwiseClone()

Crea una copia superficial del objeto Object actual.Creates a shallow copy of the current Object.

(Heredado de Object)
ToString()

Devuelve una cadena que representa el objeto actual.Returns a string that represents the current object.

(Heredado de Object)

Implementaciones de interfaz explícitas

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

Asigna un conjunto de nombres a un conjunto correspondiente de identificadores de envío.Maps a set of names to a corresponding set of dispatch identifiers.

(Heredado de Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

Obtiene la información de tipos de un objeto, que puede utilizarse para obtener la información de tipos de una interfaz.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Heredado de Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Recupera el número de interfaces de información de tipo que proporciona un objeto (0 ó 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(Heredado de Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

Proporciona acceso a las propiedades y los métodos expuestos por un objeto.Provides access to properties and methods exposed by an object.

(Heredado de Attribute)

Se aplica a

Consulte también: