DataContractAttribute Classe

Definição

Especifica que o tipo define ou implementa um contrato de dados e são serializáveis por um serializador, como o DataContractSerializer.Specifies that the type defines or implements a data contract and is serializable by a serializer, such as the DataContractSerializer. Para tornar seu tipo serializável, os autores de tipo devem definir um contrato de dados para seu 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
Herança
DataContractAttribute
Atributos

Exemplos

O exemplo a seguir serializa e desserializa uma classe chamada Person à qual o DataContractAttribute foi aplicado.The following example serializes and deserializes a class named Person to which the DataContractAttribute has been applied. Observe que as propriedades Namespace e Name foram definidas como valores que substituem as configurações padrão.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 

Comentários

Aplique o atributo DataContractAttribute a tipos (classes, estruturas ou enumerações) que são usados em operações de serialização e desserialização pelo DataContractSerializer.Apply the DataContractAttribute attribute to types (classes, structures, or enumerations) that are used in serialization and deserialization operations by the DataContractSerializer. Se você enviar ou receber mensagens usando a infraestrutura do Windows Communication Foundation (WCF), também deverá aplicar o DataContractAttribute a todas as classes que mantêm e manipulam dados enviados em mensagens.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 obter mais informações sobre contratos de dados, consulte usando contratos de dados.For more information about data contracts, see Using Data Contracts.

Você também deve aplicar o DataMemberAttribute a qualquer campo, propriedade ou evento que contenha os valores que você deseja serializar.You must also apply the DataMemberAttribute to any field, property, or event that holds values you want to serialize. Ao aplicar o DataContractAttribute, você habilita explicitamente a DataContractSerializer para serializar e desserializar os dados.By applying the DataContractAttribute, you explicitly enable the DataContractSerializer to serialize and deserialize the data.

Cuidado

Você pode aplicar o DataMemberAttribute a campos particulares.You can apply the DataMemberAttribute to private fields. Lembre-se de que os dados retornados pelo campo (mesmo se for privado) são serializados e desserializados e, portanto, podem ser exibidos ou interceptados por um usuário ou processo mal-intencionado.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 obter mais informações sobre contratos de dados, consulte os tópicos listados em usando contratos de dados.For more information about data contracts, see the topics listed in Using Data Contracts.

Contratos de dadosData Contracts

Um contrato de dados é uma descrição abstrata de um conjunto de campos com um nome e tipo de dados para cada campo.A data contract is an abstract description of a set of fields with a name and data type for each field. O contrato de dados existe fora de qualquer implementação única para permitir que os serviços em diferentes plataformas interoperem.The data contract exists outside of any single implementation to allow services on different platforms to interoperate. Desde que os dados passados entre os serviços estejam de acordo com o mesmo contrato, todos os serviços podem processar os dados.As long as the data passed between the services conforms to the same contract, all the services can process the data. Esse processamento também é conhecido como um sistema menosrígido.This processing is also known as a loosely coupled system. Um contrato de dados também é semelhante a uma interface em que o contrato especifica como os dados devem ser entregues para que possam ser processados por um aplicativo.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 exemplo, o contrato de dados pode chamar um tipo de dados chamado "Person" que tem dois campos de texto, denominados "FirstName" e "LastName".For example, the data contract may call for a data type named "Person" that has two text fields, named "FirstName" and "LastName". Para criar um contrato de dados, aplique o DataContractAttribute à classe e aplique o DataMemberAttribute a quaisquer campos ou propriedades que devam ser serializados.To create a data contract, apply the DataContractAttribute to the class and apply the DataMemberAttribute to any fields or properties that must be serialized. Quando serializados, os dados estão em conformidade com o contrato de dados que é compilado implicitamente no tipo.When serialized, the data conforms to the data contract that is implicitly built into the type.

Observação

Um contrato de dados difere significativamente de uma interface real em seu comportamento de herança.A data contract differs significantly from an actual interface in its inheritance behavior. As interfaces são herdadas por quaisquer tipos derivados.Interfaces are inherited by any derived types. Quando você aplica o DataContractAttribute a uma classe base, os tipos derivados não herdam o atributo ou o comportamento.When you apply the DataContractAttribute to a base class, the derived types do not inherit the attribute or the behavior. No entanto, se um tipo derivado tiver um contrato de dados, os membros de dados da classe base serão serializados.However, if a derived type has a data contract, the data members of the base class are serialized. No entanto, você deve aplicar o DataMemberAttribute a novos membros em uma classe derivada para torná-los serializáveis.However, you must apply the DataMemberAttribute to new members in a derived class to make them serializable.

Documentos de esquema XML e a ferramenta SvcUtilXML Schema Documents and the SvcUtil Tool

Se você estiver trocando dados com outros serviços, deverá descrever o contrato de dados.If you are exchanging data with other services, you must describe the data contract. Para a versão atual do DataContractSerializer, um esquema XML pode ser usado para definir contratos de dados.For the current version of the DataContractSerializer, an XML schema can be used to define data contracts. (Outras formas de metadados/descrição podem ser usadas para a mesma finalidade.) Para criar um esquema XML do seu aplicativo, use a ferramenta de utilitário de metadados ServiceModel (svcutil. exe) com a opção de linha de comando /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. Quando a entrada para a ferramenta é um assembly, por padrão, a ferramenta gera um conjunto de esquemas XML que definem todos os tipos de contrato de dados encontrados nesse 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. Por outro lado, você também pode usar a ferramenta svcutil. exe para criar Visual Basic ou C# definições de classe que estejam em conformidade com os requisitos de esquemas XML que usam construções que podem ser expressas por contratos de dados.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. Nesse caso, a opção de linha de comando /dconly não é necessária.In this case, the /dconly command line option is not required.

Se a entrada para a ferramenta svcutil. exe for um esquema XML, por padrão, a ferramenta criará um conjunto de classes.If the input to the Svcutil.exe tool is an XML schema, by default, the tool creates a set of classes. Se você examinar essas classes, verá que a DataContractAttribute foi aplicada.If you examine those classes, you find that the DataContractAttribute has been applied. Você pode usar essas classes para criar um novo aplicativo para processar dados que devem ser trocados por outros serviços.You can use those classes to create a new application to process data that must be exchanged with other services.

Você também pode executar a ferramenta em um ponto de extremidade que retorna um documento WSDL (Web Services Description Language) para gerar automaticamente o código e a configuração para criar um cliente 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. O código gerado inclui tipos que são marcados com o DataContractAttribute.The generated code includes types that are marked with the DataContractAttribute.

Reutilizando tipos existentesReusing Existing Types

Um contrato de dados tem dois requisitos básicos: um nome estável e uma lista de membros.A data contract has two basic requirements: a stable name and a list of members. O nome estável consiste no Uniform Resource Identifier (URI) do namespace e no nome local do contrato.The stable name consists of the namespace uniform resource identifier (URI) and the local name of the contract. Por padrão, quando você aplica o DataContractAttribute a uma classe, ele usa o nome da classe como o nome local e o namespace da classe (prefixado com "http://schemas.datacontract.org/2004/07/") como o URI do namespace.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. Você pode substituir os padrões definindo as propriedades Name e Namespace.You can override the defaults by setting the Name and Namespace properties. Você também pode alterar o namespace aplicando o ContractNamespaceAttribute ao namespace.You can also change the namespace by applying the ContractNamespaceAttribute to the namespace. Use essa funcionalidade quando você tiver um tipo existente que processa dados exatamente como você precisa, mas tem um namespace e um nome de classe diferentes do contrato de dados.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. Ao substituir os valores padrão, você pode reutilizar o tipo existente e fazer com que os dados serializados estejam em conformidade com o contrato de dados.By overriding the default values, you can reuse your existing type and have the serialized data conform to the data contract.

Observação

Em qualquer código, você pode usar a palavra DataContract em vez da DataContractAttributemais longa.In any code, you can use the word DataContract instead of the longer DataContractAttribute.

Controle de versãoVersioning

Um contrato de dados também pode acomodar versões mais recentes de si mesmo.A data contract can also accommodate later versions of itself. Ou seja, quando uma versão posterior do contrato inclui dados adicionais, esses dados são armazenados e retornados para um remetente inalterado.That is, when a later version of the contract includes extra data, that data is stored and returned to a sender untouched. Para fazer isso, implemente a interface IExtensibleDataObject.To do this, implement the IExtensibleDataObject interface.

Para obter mais informações sobre controle de versão, consulte controle de versão de contrato de dados.For more information about versioning, see Data Contract Versioning.

Construtores

DataContractAttribute()

Inicializa uma nova instância da classe DataContractAttribute.Initializes a new instance of the DataContractAttribute class.

Propriedades

IsNameSetExplicitly

Obtém se Name tiver sido definido explicitamente.Gets whether Name has been explicitly set.

IsNamespaceSetExplicitly

Obtém se Namespace tiver sido definido explicitamente.Gets whether Namespace has been explicitly set.

IsReference

Obtém ou define um valor que indica se deve preservar os dados de referência do objeto.Gets or sets a value that indicates whether to preserve object reference data.

IsReferenceSetExplicitly

Obtém se IsReference tiver sido definido explicitamente.Gets whether IsReference has been explicitly set.

Name

Obtém ou define o nome do contrato de dados para o tipo.Gets or sets the name of the data contract for the type.

Namespace

Obtém ou define o namespace para o contrato de dados para o tipo.Gets or sets the namespace for the data contract for the type.

TypeId

Quando implementado em uma classe derivada, obtém um identificador exclusivo para este Attribute.When implemented in a derived class, gets a unique identifier for this Attribute.

(Herdado de Attribute)

Métodos

Equals(Object)

Retorna um valor que indica se essa instância é igual a um objeto especificado.Returns a value that indicates whether this instance is equal to a specified object.

(Herdado de Attribute)
GetHashCode()

Retorna o código hash para a instância.Returns the hash code for this instance.

(Herdado de Attribute)
GetType()

Obtém o Type da instância atual.Gets the Type of the current instance.

(Herdado de Object)
IsDefaultAttribute()

Quando substituído em uma classe derivada, indica se o valor dessa instância é o valor padrão para a classe derivada.When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(Herdado de Attribute)
Match(Object)

Quando substituído em uma classe derivada, retorna um valor que indica se essa instância é igual a um objeto especificado.When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(Herdado de Attribute)
MemberwiseClone()

Cria uma cópia superficial do Object atual.Creates a shallow copy of the current Object.

(Herdado de Object)
ToString()

Retorna uma cadeia de caracteres que representa o objeto atual.Returns a string that represents the current object.

(Herdado de Object)

Implantações explícitas de interface

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

Mapeia um conjunto de nomes para um conjunto correspondente de identificadores de expedição.Maps a set of names to a corresponding set of dispatch identifiers.

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

Recupera as informações de tipo para um objeto, que pode ser usado para obter as informações de tipo para uma interface.Retrieves the type information for an object, which can be used to get the type information for an interface.

(Herdado de Attribute)
_Attribute.GetTypeInfoCount(UInt32)

Retorna o número de interfaces de informações do tipo que um objeto fornece (0 ou 1).Retrieves the number of type information interfaces that an object provides (either 0 or 1).

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

Fornece acesso a propriedades e métodos expostos por um objeto.Provides access to properties and methods exposed by an object.

(Herdado de Attribute)

Aplica-se a

Veja também