Visão geral do cliente WCF

Artigo
04/07/2023

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

Usando objetos de cliente WCF

Um aplicativo cliente é um aplicativo gerenciado que usa um cliente WCF para se comunicar com outro aplicativo. Para criar um aplicativo cliente para um serviço WCF, são necessárias as seguintes etapas:

Obter o contrato de serviço, as associações e as informações de endereço de um ponto de extremidade de serviço.
Criar um cliente WCF que use essas informações.
Chamar as operações.
Fechar o objeto cliente do WCF.

As seções a seguir abordam essas etapas e fazem breves introduções às seguintes questões:

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 clientes modelam contratos usando atributos gerenciados, interfaces e métodos. Para se conectar a um serviço em um aplicativo cliente, é necessário obter as informações de tipo do contrato de serviço. Normalmente, você obtém informações de tipo para o contrato de serviço usando a Ferramenta do Utilitário de Metadados do ServiceModel (Svcutil.exe). O utilitário baixa metadados do serviço, os converte em um arquivo de código-fonte gerenciado na linguagem de sua preferência e cria um arquivo de configuração de aplicativo cliente que pode ser usado para configurar o objeto de cliente WCF. Por exemplo, se você pretende criar um objeto de cliente WCF para chamar um MyCalculatorService e sabe que os metadados desse serviço serão publicados em http://computerName/MyCalculatorService/Service.svc?wsdl, o exemplo de código a seguir mostra como usar o Svcutil.exe para obter um arquivo ClientCode.vb que contenha o contrato de serviço em 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 poderá usar para criar um objeto de cliente WCF. Você pode usar o arquivo de configuração para configurar o objeto de 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 os contratos, consulte Contratos.

Criar um novo 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 para que ao criar um e configurá-lo você possa usar o objeto de cliente diretamente para chamar as operações de serviço. O tempo de execução do WCF converte as chamadas de método em mensagens, as envia para o serviço, escuta a resposta e retorna esses valores ao objeto de cliente WCF como valores de retorno ou como parâmetros out ou ref.

Você também pode usar objetos de canal de cliente WCF para se conectar aos serviços e utilizá-los. Para obter detalhes, consulte a Arquitetura do Cliente WCF.

Criando um novo objeto do WCF

Para ilustrar o uso de uma classe ClientBase<TChannel>, suponha que o seguinte contrato de serviço simples foi gerado em um aplicativo de serviço.

Observação

Se você estiver usando o Visual Studio para criar o cliente WCF, os objetos serão automaticamente carregados no pesquisador de objetos quando você adicionar uma referência de serviço ao 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 terá a seguinte aparência:

[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, configurada e, em seguida, usada para se conectar a um serviço do tipo ISampleService.

É recomendável criar o objeto de cliente ECF primeiro e, depois, usá-lo e fechá-lo em um único bloco try/catch. Você não deve usar a instrução using (Using no Visual Basic), porque isso 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, associações e endereços

Para que você possa criar um objeto de cliente WCF, configure-o. 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 mais informações sobre pontos de extremidade, consulte Pontos de extremidade, endereços, associações e contratos.) Normalmente, essas informações são encontradas no elemento <ponto de extremidade> em um arquivo de configuração de aplicativo cliente, como o arquivo gerado pela ferramenta Svcutil.exe, e são carregadas automaticamente quando você cria o objeto de cliente. Os dois tipos de cliente WCF também têm sobrecargas que permitem que você especifique essas informações de modo programático.

Por exemplo, um arquivo de configuração gerado de 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 elemento <client>. 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 de cliente criado e configurado, crie um bloco try/catch, chame as operações da mesma maneira que faria se o objeto fosse local e feche o objeto de cliente WCF. Quando o aplicativo cliente chama a primeira operação, o WCF abre automaticamente o canal subjacente, e este é fechado quando o objeto é reciclado. (Como alternativa, você também pode abrir e fechar explicitamente o canal antes ou após 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ê poderá chamar as operações criando um objeto de cliente WCF e chamando seus métodos, conforme demonstrado pelo seguinte exemplo de código. A abertura, a chamada e o fechamento do objeto de cliente WCF ocorre em um único bloco try/catch. Para obter mais informações, consulte Acessar serviços usando um cliente WCF e Usar Fechar e Anular para liberar recursos de cliente 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

Poderão ocorrer exceções em um aplicativo cliente quando o canal de cliente subjacente for aberto (explícita ou automaticamente, durante o chamamento de uma operação), o objeto de cliente ou de canal for usado para chamar operações, ou o canal de cliente subjacente for fechado. É recomendável que os aplicativos possam, pelo menos, manipular as exceções System.TimeoutException e System.ServiceModel.CommunicationException possíveis, além de qualquer objeto System.ServiceModel.FaultException lançado como resultado de falhas de SOAP retornadas pelas 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 que mostra como manipular erros em um cliente, consulte Exceções esperadas.

Configurando e protegendo clientes

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

Por exemplo, os requisitos de segurança dos contratos de serviço são declarados na interface do contrato de serviço e, se a ferramenta Svcutil.exe tiver criado um arquivo de configuração, este geralmente conterá uma associação capaz de oferecer suporte aos requisitos de segurança do serviço. Em alguns casos, no entanto, talvez seja necessário definir configurações de segurança adicional, como configurar credenciais do cliente. Para obter informações completas sobre a configuração da segurança dos clientes WCF, consulte Proteger clientes.

Além disso, algumas modificações personalizadas podem ser habilitadas em aplicativos cliente, como comportamentos personalizados de tempo de execução. Para obter mais informações sobre como configurar um comportamento personalizado do cliente, consulte Configurar 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 um tipo 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 para serviços que chamam o objeto de retorno de chamada. Para obter mais informações, consulte Serviços de duplex. Para obter um exemplo completo, consulte Duplex.

Em computadores com o Windows XP que executam os Serviços de Informações da Internet (IIS) 5.1, os clientes duplex devem especificar um endereço básico de cliente usando a classe System.ServiceModel.WSDualHttpBinding; do contrário, uma exceção será lançada. 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 exemplo de 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 maneira como as operações serão chamadas fica totalmente a cargo do desenvolvedor do cliente. Isso acontece porque as mensagens que compõem uma operação podem ser mapeadas para métodos síncronos ou assíncronos quando expressas em código gerenciado. Portanto, se você quiser compilar um cliente que chama operações de forma assíncrona, use o Svcutil.exe para gerar um 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.

Chamando serviços por meio de canais de cliente 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 chamar serviços usando o contrato de serviço de destino com a classe System.ServiceModel.ChannelFactory<TChannel>. Para obter detalhes, consulte a Arquitetura do Cliente WCF.

Compartilhar via