Compartilhar via

Usando contratos de dados

Um contrato de dados é um contrato formal entre um serviço e um cliente que descreve abstratamente os dados a serem trocados. Ou seja, para se comunicar, o cliente e o serviço não precisam compartilhar os mesmos tipos, apenas os mesmos contratos de dados. Um contrato de dados define precisamente, para cada parâmetro ou tipo de retorno, quais dados são serializados (transformados em XML) a serem trocados.

Noções básicas do contrato de dados

O Windows Communication Foundation (WCF) usa um mecanismo de serialização chamado Serializador de Contrato de Dados por padrão para serializar e desserializar dados (convertê-los de e para XML). Todos os tipos primitivos do .NET Framework, como inteiros e cadeias de caracteres, bem como determinados tipos tratados como primitivos, como DateTime e XmlElement, podem ser serializados sem nenhuma outra preparação e são considerados como tendo contratos de dados padrão. Muitos tipos do .NET Framework também têm contratos de dados existentes. Para obter uma lista completa de tipos serializáveis, consulte Tipos compatíveis com o Serializador de Contrato de Dados.

Novos tipos complexos criados devem ter um contrato de dados definido para que eles sejam serializáveis. Por padrão, o DataContractSerializer infere o contrato de dados e serializa todos os tipos publicamente visíveis. Todas as propriedades públicas de leitura/gravação e campos do tipo são serializadas. Você pode excluir membros da serialização utilizando o IgnoreDataMemberAttribute. Você também pode criar explicitamente um contrato de dados usando DataContractAttribute e DataMemberAttribute atributos. Normalmente, isso é feito aplicando o DataContractAttribute atributo ao tipo. Esse atributo pode ser aplicado a classes, estruturas e enumerações. O atributo DataMemberAttribute deve ser aplicado a cada membro do tipo de contrato de dados para indicar que é um membro de dados, ou seja, deve ser serializado. Para obter mais informações, consulte Tipos Serializáveis.

Exemplo

O exemplo a seguir mostra um contrato de serviço (uma interface) ao qual os atributos ServiceContractAttribute e OperationContractAttribute foram explicitamente aplicados. O exemplo mostra que os tipos primitivos não exigem um contrato de dados, enquanto um tipo complexo exige.

[ServiceContract]
public interface ISampleInterface
{
    // No data contract is required since both the parameter
    // and return types are primitive types.
    [OperationContract]
    double SquareRoot(int root);

    // No Data Contract required because both parameter and return
    // types are marked with the SerializableAttribute attribute.
    [OperationContract]
    System.Drawing.Bitmap GetPicture(System.Uri pictureUri);

    // The MyTypes.PurchaseOrder is a complex type, and thus
    // requires a data contract.
    [OperationContract]
    bool ApprovePurchaseOrder(MyTypes.PurchaseOrder po);
}

<ServiceContract()> _
Public Interface ISampleInterface
    ' No data contract is required since both the parameter and return 
    ' types are both primitive types.
    <OperationContract()> _
    Function SquareRoot(ByVal root As Integer) As Double

    ' No Data Contract required because both parameter and return 
    ' types are marked with the SerializableAttribute attribute.
    <OperationContract()> _
    Function GetPicture(ByVal pictureUri As System.Uri) As System.Drawing.Bitmap

    ' The MyTypes.PurchaseOrder is a complex type, and thus 
    ' requires a data contract.
    <OperationContract()> _
    Function ApprovePurchaseOrder(ByVal po As MyTypes.PurchaseOrder) As Boolean
End Interface

O exemplo a seguir mostra como um contrato de dados para o tipo MyTypes.PurchaseOrder é criado ao aplicar os atributos DataContractAttribute e DataMemberAttribute à classe e aos seus membros.

namespace MyTypes
{
    [DataContract]
    public class PurchaseOrder
    {
        private int poId_value;

        // Apply the DataMemberAttribute to the property.
        [DataMember]
        public int PurchaseOrderId
        {

            get { return poId_value; }
            set { poId_value = value; }
        }
    }
}

Namespace MyTypes
    <System.Runtime.Serialization.DataContractAttribute()> _
    Public Class PurchaseOrder
        Private poId_value As Integer

        ' Apply the DataMemberAttribute to the property.

        <DataMember()> _
        Public Property PurchaseOrderId() As Integer

            Get
                Return poId_value
            End Get
            Set
                poId_value = value
            End Set
        End Property
    End Class
End Namespace

Anotações

As notas a seguir fornecem itens a serem considerados ao criar contratos de dados:

  • O IgnoreDataMemberAttribute atributo só é respeitado quando usado com tipos não marcados. Isso inclui tipos que não são marcados com um dos atributos DataContractAttribute, SerializableAttribute, CollectionDataContractAttribute ou EnumMemberAttribute, ou marcados como serializáveis por qualquer outro meio (como IXmlSerializable).

  • Você pode aplicar o DataMemberAttribute atributo a campos e propriedades.

  • Os níveis de acessibilidade do membro (internos, privados, protegidos ou públicos) não afetam o contrato de dados de forma alguma.

  • O DataMemberAttribute atributo será ignorado se for aplicado a membros estáticos.

  • Durante a serialização, o código de obtenção de propriedade é chamado para que os membros de dados de propriedade obtenham o valor das propriedades a serem serializadas.

  • Durante a desserialização, um objeto não inicializado é criado pela primeira vez, sem chamar nenhum construtor no tipo. Em seguida, todos os membros de dados são desserializados.

  • Durante a desserialização, o código do conjunto de propriedades é chamado para que os membros de dados de propriedade definam as propriedades como o valor sendo desserializado.

  • Para que um contrato de dados seja válido, deve ser possível serializar todos os seus elementos de dados. Para obter uma lista completa de tipos serializáveis, consulte Tipos compatíveis com o Serializador de Contrato de Dados.

    Tipos genéricos são tratados exatamente da mesma maneira que tipos não genéricos. Não há requisitos especiais para parâmetros genéricos. Por exemplo, considere o tipo a seguir.

[DataContract]
public class MyGenericType1<T>
{
    // Code not shown.
}

<DataContract()> _
Public Class MyGenericType1(Of T)
    ' Code not shown.
End Class

Esse tipo é serializável se o tipo usado para o parâmetro de tipo genérico (T) é serializável ou não. Como deve ser possível serializar todos os membros de dados, o tipo a seguir só será serializável se o parâmetro de tipo genérico também for serializável, conforme mostrado no código a seguir.

[DataContract]
public class MyGenericType2<T>
{
    [DataMember]
    T theData;
}

<DataContract()> _
Public Class MyGenericType2(Of T)
    <DataMember()> _
    Dim theData As T
End Class

Para obter um exemplo de código completo de um serviço WCF que define um contrato de dados, consulte o exemplo de Contrato de Dados Básico .

Consulte também