DataContractAttribute Classe

Definição

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

Herança

Object

Attribute

DataContractAttribute

Atributos

AttributeUsageAttribute

Exemplos

O exemplo seguinte serializa e desserializa uma classe nomeada Person à qual o foi aplicado DataContractAttribute . Note que as Namespace propriedades e Name foram definidas para valores que sobrepõem as definições padrão.

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

Observações

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. Se você enviar ou receber mensagens usando a infraestrutura do Windows Communication Foundation (WCF), você também deve aplicar o DataContractAttribute a quaisquer classes que contêm e manipulam dados enviados em mensagens. Para obter mais informações sobre contratos de dados, consulte Usando contratos de dados.

Você também deve aplicar o DataMemberAttribute a qualquer campo, propriedade ou evento que contenha valores que você deseja serializar. Ao aplicar o DataContractAttribute, você habilita explicitamente o DataContractSerializer para serializar e desserializar os dados.

Para obter mais informações sobre contratos de dados, consulte os tópicos listados em Usando contratos de dados.

Contratos de dados

Um contrato de dados é uma descrição abstrata de um conjunto de campos com um nome e um tipo de dados para cada campo. O contrato de dados existe fora de qualquer implementação única para permitir que os serviços em diferentes plataformas interoperem. Desde que os dados transmitidos entre os serviços estejam em conformidade com o mesmo contrato, todos os serviços podem processar os dados. Este processamento também é conhecido como um sistema de acoplamento flexível. Um contrato de dados também é semelhante a uma interface, na medida em que o contrato especifica como os dados devem ser entregues para que possam ser processados por um aplicativo. Por exemplo, o contrato de dados pode chamar um tipo de dados chamado "Pessoa" que tenha dois campos de texto, chamados "Nome" e "Sobrenome". Para criar um contrato de dados, aplique o DataContractAttribute à classe e aplique o DataMemberAttribute a quaisquer campos ou propriedades que devem ser serializados. Quando serializados, os dados estão em conformidade com o contrato de dados que é implicitamente incorporado no tipo.

Documentos do esquema XML e a ferramenta SvcUtil

Se estiver a trocar dados com outros serviços, deve descrever o contrato de dados. Para a versão atual do DataContractSerializer, um esquema XML pode ser usado para definir contratos de dados. (Podem ser utilizadas outras formas de metadados/descrição para o mesmo fim.) Para criar um esquema XML a partir do seu aplicativo, use a ServiceModel Metadata Utility Tool (Svcutil.exe) com a opção de linha de comando /dconly . 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. Por outro lado, você também pode usar a ferramenta Svcutil.exe para criar definições de classe Visual Basic ou C# que estejam em conformidade com os requisitos de esquemas XML que usam construções que podem ser expressas por contratos de dados. Nesse caso, a opção de linha de comando /dconly não é necessária.

Se a entrada para a ferramenta Svcutil.exe for um esquema XML, por padrão, a ferramenta criará um conjunto de classes. Se você examinar essas classes, verá que a DataContractAttribute foi aplicada. Você pode usar essas classes para criar um novo aplicativo para processar dados que devem ser trocados com outros serviços.

Pode também executar a ferramenta num ponto de extremidade que devolva um documento WSDL (Web Services Description Language) para gerar automaticamente o código e a configuração necessários para criar um cliente WCF (Windows Communication Foundation). O código gerado inclui tipos marcados com o DataContractAttribute.

Reutilizar tipos existentes

Um contrato de dados tem dois requisitos básicos: um nome estável e uma lista de membros. O nome estável consiste no URI (uniform resource identifier) do namespace e no nome local do contrato. 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. Você pode substituir os valores padrão ao definir as propriedades Name e Namespace. Você também pode alterar o namespace aplicando o ContractNamespaceAttribute ao namespace. Use esse recurso quando tiver um tipo existente que processe dados exatamente como você precisa, mas tenha um namespace e um nome de classe diferentes do contrato de dados. Ao substituir os valores padrão, você pode reutilizar seu tipo existente e fazer com que os dados serializados estejam em conformidade com o contrato de dados.

Versioning

Um contrato de dados também pode acomodar versões posteriores de si mesmo. Ou seja, quando uma versão posterior do contrato inclui dados extras, esses dados são armazenados e devolvidos a um remetente intocados. Para fazer isso, implemente a IExtensibleDataObject interface.

Para obter mais informações sobre controle de versão, consulte Controle de versão de contrato de dados.

Ver também

• IExtensibleDataObject
• ExtensionDataObject
• DataContractSerializer
• DataMemberAttribute
• ISerializable
• KnownTypeAttribute
• Usando contratos de dados