Compartilhar via

Visão geral do cliente WCF

Esta seção descreve o que os aplicativos cliente fazem, como configurar, criar e usar um cliente WCF (Windows Communication Foundation) e como proteger aplicativos cliente.

Usando objetos de cliente do WCF

Um aplicativo cliente é um aplicativo gerenciado que usa um cliente WCF para se comunicar com outro aplicativo. A criação de um aplicativo cliente para um serviço WCF requer as seguintes etapas:

  1. Obter o contrato de serviço, as associações e as informações de endereço de um ponto de extremidade de serviço.

  2. Crie um cliente WCF usando essas informações.

  3. Chamar as operações.

  4. Feche o objeto cliente WCF.

As seções a seguir discutem estas etapas e fornecem breves introduçãos aos seguintes problemas:

  • Tratamento de erros.

  • Configurando e protegendo clientes.

  • Criando objetos de retorno de chamada para serviços duplex.

  • Chamando serviços de modo assíncrono.

  • Chamando serviços por meio de canais de cliente.

Obter o contrato de serviço, as associações e os endereços

No WCF, os serviços e os clientes modelam contratos usando atributos, interfaces e métodos gerenciados. Para se conectar a um serviço em um aplicativo cliente, você precisa obter as informações de tipo para o contrato de serviço. Normalmente, você obtém informações de tipo para o contrato de serviço usando a Ferramenta de Utilitário de Metadados serviceModel (Svcutil.exe). O utilitário baixa metadados do serviço, converte-os em um arquivo de código-fonte gerenciado no idioma de sua escolha e cria um arquivo de configuração de aplicativo cliente que você pode usar para configurar o objeto cliente WCF. Por exemplo, se você vai criar um objeto de cliente WCF para invocar um MyCalculatorService, e você sabe que os metadados desse serviço são publicados em http://computerName/MyCalculatorService/Service.svc?wsdl, então o exemplo de código a seguir mostra como usar Svcutil.exe para obter um arquivo ClientCode.vb que contém o contrato de serviço no código gerenciado.

svcutil /language:vb /out:ClientCode.vb /config:app.config http://computerName/MyCalculatorService/Service.svc?wsdl

Você pode compilar esse código de contrato no aplicativo cliente ou em outro assembly que o aplicativo cliente pode usar para criar um objeto cliente WCF. Você pode usar o arquivo de configuração para configurar o objeto cliente para se conectar corretamente ao serviço.

Para obter um exemplo desse processo, consulte Como criar um cliente. Para obter informações mais completas sobre contratos, consulte Contratos.

Criar um objeto de cliente WCF

Um cliente WCF é um objeto local que representa um serviço WCF em um formulário que o cliente pode usar para se comunicar com o serviço remoto. Os tipos de cliente WCF implementam o contrato de serviço de destino, portanto, ao criar um e configurá-lo, você pode usar o objeto cliente diretamente para invocar operações de serviço. O runtime do WCF converte as chamadas de método em mensagens, envia-as ao serviço, escuta a resposta e retorna esses valores para o objeto cliente WCF como valores de retorno ou como parâmetros out ou ref.

Você também pode usar objetos do canal cliente do WCF para se conectar e usar serviços. Para obter detalhes, consulte a arquitetura do cliente do WCF.

Criando um novo objeto WCF

Para ilustrar o uso de uma ClientBase<TChannel> classe, suponha que o contrato de serviço simples a seguir tenha sido gerado a partir de um aplicativo de serviço.

Observação

Se você estiver usando o Visual Studio para criar seu cliente WCF, os objetos serão carregados automaticamente no navegador do objeto quando você adicionar uma referência de serviço ao seu projeto.

[System.ServiceModel.ServiceContractAttribute(
  Namespace = "http://microsoft.wcf.documentation"
)]
public interface ISampleService
{
    [System.ServiceModel.OperationContractAttribute(
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethod",
      ReplyAction = "http://microsoft.wcf.documentation/ISampleService/SampleMethodResponse"
    )]
    [System.ServiceModel.FaultContractAttribute(
      typeof(microsoft.wcf.documentation.SampleFault),
      Action = "http://microsoft.wcf.documentation/ISampleService/SampleMethodSampleFaultFault"
    )]
    string SampleMethod(string msg);
}

Se você não estiver usando o Visual Studio, examine o código de contrato gerado para localizar o tipo que estende o ClientBase<TChannel> e a interface de contrato de serviço ISampleService. Nesse caso, esse tipo se parece com o seguinte código:

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public partial class SampleServiceClient : System.ServiceModel.ClientBase<ISampleService>, ISampleService
{

    public SampleServiceClient()
    {
    }

    public SampleServiceClient(string endpointConfigurationName)
        :
            base(endpointConfigurationName)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, string remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(string endpointConfigurationName, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(endpointConfigurationName, remoteAddress)
    {
    }

    public SampleServiceClient(System.ServiceModel.Channels.Binding binding, System.ServiceModel.EndpointAddress remoteAddress)
        :
            base(binding, remoteAddress)
    {
    }
    public string SampleMethod(string msg)
    {
        return base.Channel.SampleMethod(msg);
    }
}

Essa classe pode ser criada como um objeto local usando um dos construtores, configurado e, em seguida, usado para se conectar a um serviço do tipo ISampleService.

É recomendável que você crie seu objeto cliente WCF primeiro e, em seguida, use-o e feche-o dentro de um único bloco try/catch. Não use a using instrução (Using no Visual Basic) porque ela pode mascarar exceções em determinados modos de falha. Para obter mais informações, consulte as seções a seguir, bem como Usar Fechar e Anular para liberar recursos de cliente WCF.

Contratos, vinculações e endereços

Antes de criar um objeto cliente WCF, você deve configurar o objeto cliente. Especificamente, ele deve ter um ponto de extremidade de serviço a ser usado. O ponto de extremidade é a combinação de um contrato de serviço, uma associação e um endereço. (Para obter mais informações sobre pontos de extremidade, consulte Pontos de Extremidade: Endereços, Associações e Contratos.) Normalmente, essas informações estão localizadas no elemento de <ponto> de extremidade em um arquivo de configuração de aplicativo cliente, como aquele que a ferramenta Svcutil.exe gera e são carregadas automaticamente quando você cria o objeto cliente. Ambos os tipos de cliente WCF também têm sobrecargas que permitem que você especifique essas informações programaticamente.

Por exemplo, um arquivo de configuração gerado para um ISampleService usado nos exemplos anteriores contém as seguintes informações de ponto de extremidade.

<configuration>
    <system.serviceModel>
        <bindings>
            <wsHttpBinding>
                <binding name="WSHttpBinding_ISampleService" closeTimeout="00:01:00"
                    openTimeout="00:01:00" receiveTimeout="00:01:00" sendTimeout="00:01:00"
                    bypassProxyOnLocal="false" transactionFlow="false" hostNameComparisonMode="StrongWildcard"
                    maxBufferPoolSize="524288" maxReceivedMessageSize="65536"
                    messageEncoding="Text" textEncoding="utf-8" useDefaultWebProxy="true"
                    allowCookies="false">
                    <readerQuotas maxDepth="32" maxStringContentLength="8192" maxArrayLength="16384"
                        maxBytesPerRead="4096" maxNameTableCharCount="16384" />
                    <reliableSession ordered="true" inactivityTimeout="00:10:00"
                        enabled="false" />
                    <security mode="Message">
                        <transport clientCredentialType="None" proxyCredentialType="None"
                            realm="" />
                        <message clientCredentialType="Windows" negotiateServiceCredential="true"
                            algorithmSuite="Default" establishSecurityContext="true" />
                    </security>
                </binding>
            </wsHttpBinding>
        </bindings>
        <client>
            <endpoint address="http://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

Esse arquivo de configuração especifica um ponto de extremidade de destino no <client> elemento. Para obter mais informações sobre como usar vários pontos de extremidade de destino, consulte os construtores ClientBase<TChannel> ou ChannelFactory<TChannel>.

Chamando operações

Depois que você tiver um objeto cliente criado e configurado, crie um bloco try/catch, chame operações da mesma maneira que faria se o objeto fosse local e feche o objeto cliente WCF. Quando o aplicativo cliente chama a primeira operação, o WCF abre automaticamente o canal subjacente e o canal subjacente é fechado quando o objeto é reciclado. (Como alternativa, você também pode abrir e fechar explicitamente o canal antes ou depois de chamar outras operações.)

Por exemplo, se você tiver o seguinte contrato de serviço:

namespace Microsoft.ServiceModel.Samples
{
    using System;
    using System.ServiceModel;

    [ServiceContract(Namespace = "http://Microsoft.ServiceModel.Samples")]
    public interface ICalculator
   {
        [OperationContract]
        double Add(double n1, double n2);
        [OperationContract]
        double Subtract(double n1, double n2);
        [OperationContract]
        double Multiply(double n1, double n2);
        [OperationContract]
        double Divide(double n1, double n2);
    }
}

Namespace Microsoft.ServiceModel.Samples

    Imports System
    Imports System.ServiceModel

    <ServiceContract(Namespace:= _
    "http://Microsoft.ServiceModel.Samples")> _
   Public Interface ICalculator
        <OperationContract> _
        Function Add(n1 As Double, n2 As Double) As Double
        <OperationContract> _
        Function Subtract(n1 As Double, n2 As Double) As Double
        <OperationContract> _
        Function Multiply(n1 As Double, n2 As Double) As Double
        <OperationContract> _
     Function Divide(n1 As Double, n2 As Double) As Double
End Interface

Você pode chamar operações criando um objeto cliente WCF e chamando seus métodos, como demonstra o exemplo de código a seguir. A abertura, a chamada e o fechamento do objeto cliente WCF ocorrem em um único bloco try/catch. Para obter mais informações, consulte Acessando serviços usando um cliente WCF e use Fechar e Anular para liberar recursos de cliente do WCF.

CalculatorClient wcfClient = new CalculatorClient();
try
{
    Console.WriteLine(wcfClient.Add(4, 6));
    wcfClient.Close();
}
catch (TimeoutException timeout)
{
    // Handle the timeout exception.
    wcfClient.Abort();
}
catch (CommunicationException commException)
{
    // Handle the communication exception.
    wcfClient.Abort();
}

Manipulando erros

Exceções podem ocorrer em um aplicativo cliente ao abrir o canal do cliente subjacente (seja explicitamente ou automaticamente chamando uma operação), usando o cliente ou o objeto de canal para chamar operações ou ao fechar o canal do cliente subjacente. É recomendável que, no mínimo, os aplicativos estejam preparados para lidar com possíveis exceções System.TimeoutException e System.ServiceModel.CommunicationException, além de quaisquer objetos System.ServiceModel.FaultException lançados como resultado de falhas SOAP, retornadas por operações. As falhas de SOAP especificadas no contrato de operação são geradas para aplicativos cliente como System.ServiceModel.FaultException<TDetail>, em que o parâmetro de tipo é o tipo de detalhe da falha de SOAP. Para obter mais informações sobre como lidar com condições de erro em um aplicativo cliente, consulte Envio e recebimento de falhas. Para obter um exemplo completo, mostra como lidar com erros em um cliente, consulte Exceções Esperadas.

Configurando e protegendo clientes

A configuração de um cliente começa com o carregamento necessário de informações de ponto de extremidade de destino para o cliente ou objeto de canal, geralmente de um arquivo de configuração, embora você também possa carregar essas informações programaticamente usando os construtores e propriedades do cliente. No entanto, etapas de configuração adicionais são necessárias para habilitar determinado comportamento do cliente e para muitos cenários de segurança.

Por exemplo, os requisitos de segurança para contratos de serviço são declarados na interface do contrato de serviço e, se Svcutil.exe criou um arquivo de configuração, esse arquivo geralmente contém uma associação capaz de dar suporte aos requisitos de segurança do serviço. Em alguns casos, no entanto, mais configuração de segurança pode ser necessária, como configurar credenciais do cliente. Para obter informações completas sobre a configuração de segurança para clientes do WCF, consulte Proteção de clientes.

Além disso, algumas modificações personalizadas podem ser habilitadas em aplicativos cliente, como comportamentos de runtime personalizados. Para obter mais informações sobre como configurar um comportamento personalizado do cliente, consulte Configurando comportamentos do cliente.

Criando objetos de retorno de chamada para serviços duplex

Os serviços duplex especificam um contrato de retorno de chamada que o aplicativo cliente deve implementar para fornecer um objeto de retorno de chamada que o serviço chamará de acordo com os requisitos do contrato. Embora os objetos de retorno de chamada não sejam serviços completos (por exemplo, você não pode iniciar um canal com um objeto de retorno de chamada), para fins de implementação e configuração, eles podem ser considerados como uma espécie de serviço.

Os clientes dos serviços duplex devem:

  • Implementar uma classe de contrato de retorno de chamada.

  • Criar uma instância da classe de implementação de contrato de retorno de chamada e utilizá-la para criar o objeto System.ServiceModel.InstanceContext que você passa para o construtor do cliente WCF.

  • Chamar operações e manipular retornos de chamada de operação.

Os objetos de cliente WCF duplex funcionam como seus equivalentes não duplex. A exceção é que eles expõem a funcionalidade necessária para oferecer suporte aos retornos de chamada, incluindo a configuração do serviço de retorno de chamada.

Por exemplo, você pode controlar vários aspectos do comportamento de runtime do objeto de retorno de chamada usando as propriedades do atributo System.ServiceModel.CallbackBehaviorAttribute da classe de retorno de chamada. Outro exemplo é o uso da classe System.ServiceModel.Description.CallbackDebugBehavior para habilitar o retorno das informações de exceção aos serviços que chamam o objeto callback. Para obter mais informações, consulte Duplex Services. Para obter um exemplo completo, consulte Duplex.

Em computadores Windows XP que executam o IIS (Serviços de Informações da Internet) 5.1, os clientes duplex devem especificar um endereço base do cliente usando a System.ServiceModel.WSDualHttpBinding classe ou uma exceção é gerada. O exemplo de código a seguir mostra como fazer isso no código.

WSDualHttpBinding dualBinding = new WSDualHttpBinding();
EndpointAddress endptadr = new EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server");
dualBinding.ClientBaseAddress = new Uri("http://localhost:8000/DuplexTestUsingCode/Client/");


Dim dualBinding As New WSDualHttpBinding()
Dim endptadr As New EndpointAddress("http://localhost:12000/DuplexTestUsingCode/Server")
dualBinding.ClientBaseAddress = New Uri("http://localhost:8000/DuplexTestUsingCode/Client/")

O código a seguir mostra como fazer isso em um arquivo de configuração

<client>
  <endpoint
    name ="ServerEndpoint"
    address="http://localhost:12000/DuplexUsingConfig/Server"
    bindingConfiguration="WSDualHttpBinding_IDuplex"
    binding="wsDualHttpBinding"
    contract="IDuplex"
/>
</client>
<bindings>
  <wsDualHttpBinding>
    <binding
      name="WSDualHttpBinding_IDuplex"
      clientBaseAddress="http://localhost:8000/myClient/"
    />
  </wsDualHttpBinding>
</bindings>

Chamando serviços de modo assíncrono

A forma como as operações são chamadas cabe inteiramente ao desenvolvedor cliente. Isso ocorre porque as mensagens que compõem uma operação podem ser mapeadas para métodos síncronos ou assíncronos quando expressas no código gerenciado. Portanto, se você quiser criar um cliente que chame operações de forma assíncrona, poderá usar Svcutil.exe para gerar código de cliente assíncrono usando a opção /async . Para obter mais informações, confira Como chamar operações de serviço de forma assíncrona.

Serviços de chamada usando canais de cliente do WCF

Os tipos de cliente WCF estendem o ClientBase<TChannel>, que é derivado da interface System.ServiceModel.IClientChannel para expor o sistema de canal subjacente. Você pode invocar serviços usando o contrato de serviço de destino com a System.ServiceModel.ChannelFactory<TChannel> classe. Para obter detalhes, consulte a arquitetura do cliente do WCF.

Consulte também

  • Last updated on