Visão geral do cliente WCF

Artigo
03/05/2024

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 WCF

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

Obtenha o contrato de serviço, as associações e as informações de endereço para um ponto de extremidade de serviço.
Crie um cliente WCF usando essas informações.
Operações de chamada.
Feche o objeto de cliente WCF.

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

Tratamento de erros.
Configuração e proteção de clientes.
Criação de objetos de retorno de chamada para serviços duplex.
Chamando serviços de forma assíncrona.
Chamando serviços usando canais de cliente.

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

No WCF, serviços e 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 ServiceModel Metadata Utility Tool (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 seu objeto de cliente WCF. Por exemplo, se você for criar um objeto de cliente WCF para invocar um MyCalculatorService, e souber que os metadados desse serviço são publicados em http://computerName/MyCalculatorService/Service.svc?wsdl, o exemplo de código a seguir mostra como usar Svcutil.exe para obter um ClientCode.vb arquivo que contém 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 pode usar para criar um objeto de 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 formato 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 tempo de execução do WCF converte as chamadas de método em mensagens, envia-as para o serviço, escuta a resposta e retorna esses valores para o objeto de cliente WCF como valores de retorno ou outref parâmetros.

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

Criando um novo objeto WCF

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

Nota

Se você estiver usando o Visual Studio para criar seu cliente WCF, os objetos são carregados automaticamente no navegador de objetos quando você adiciona 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 se estende ClientBase<TChannel> e a interface ISampleServicedo contrato de serviço . 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, configurada e, em seguida, usada para se conectar a um serviço do tipo ISampleService.

É recomendável que você crie seu objeto de 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 abortar para liberar recursos de cliente WCF.

Contratos, Vinculações e Endereços

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

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

<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>

Este 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 o ClientBase<TChannel> ou os ChannelFactory<TChannel> construtores.

Operações de chamada

Depois de criar e configurar um objeto cliente, 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 de cliente WCF e chamando seus métodos, como demonstra o exemplo de código a seguir. A abertura, chamada e fechamento do objeto cliente WCF ocorre dentro de um único bloco try/catch. Para obter mais informações, consulte Acessando 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();
}

Tratamento de erros

Exceções podem ocorrer em um aplicativo cliente ao abrir o canal do cliente subjacente (seja explícita ou automaticamente chamando uma operação), usando o cliente ou objeto de canal para chamar operações ou ao fechar o canal do cliente subjacente. Recomenda-se, no mínimo, que os aplicativos esperem lidar com possíveis System.TimeoutException e System.ServiceModel.CommunicationException exceções, além de quaisquer System.ServiceModel.FaultException objetos lançados como resultado de falhas SOAP retornadas por operações. As falhas SOAP especificadas no contrato de operação são geradas para aplicativos cliente como um System.ServiceModel.FaultException<TDetail> onde o parâmetro type é o tipo de detalhe da falha SOAP. Para obter mais informações sobre como lidar com condições de erro em um aplicativo cliente, consulte Enviando e recebendo falhas. Para obter um exemplo completo de 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 a partir 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 suportar os requisitos de segurança do serviço. Em alguns casos, no entanto, mais configuração de segurança pode ser necessária, como a configuração de credenciais de cliente. Para obter informações completas sobre a configuração de segurança para clientes WCF, consulte Protegendo clientes.

Além disso, algumas modificações personalizadas podem ser habilitadas em aplicativos cliente, como comportamentos de tempo de execução personalizados. Para obter mais informações sobre como configurar um comportamento de cliente personalizado, consulte Configurando comportamentos de 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 para que o serviço chame 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 pensados como um tipo de serviço.

Os clientes de serviços duplex devem:

Implemente uma classe de contrato de retorno de chamada.
Crie uma instância da classe de implementação de contrato de retorno de chamada e use-a para criar o System.ServiceModel.InstanceContext objeto que você passa para o construtor do cliente WCF.
Invoque operações e manipule retornos de chamada de operação.

Os objetos de cliente WCF duplex funcionam como suas contrapartes não duplex, com a exceção de que expõem a funcionalidade necessária para dar suporte a retornos de chamada, incluindo a configuração do serviço de retorno de chamada.

Por exemplo, você pode controlar vários aspetos do comportamento de tempo de execução do objeto de retorno de chamada usando propriedades do System.ServiceModel.CallbackBehaviorAttribute atributo na classe de retorno de chamada. Outro exemplo é o uso da classe para habilitar o System.ServiceModel.Description.CallbackDebugBehavior retorno de informações de exceção para serviços que chamam o objeto de retorno de chamada. Para obter mais informações, consulte Serviços duplex. Para obter um exemplo completo, consulte Duplex.

Em computadores com 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 é 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 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 forma assíncrona

A forma como as operações são chamadas depende inteiramente do desenvolvedor do 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 em código gerenciado. Portanto, se você quiser criar um cliente que chama operações de forma assíncrona, você pode usar Svcutil.exe para gerar código de cliente assíncrono usando a /async opção. Para obter mais informações, consulte Como chamar operações de serviço de forma assíncrona.

Chamando serviços usando canais de cliente WCF

Os tipos de cliente WCF estendem ClientBase<TChannel>, que deriva da interface para expor o sistema de System.ServiceModel.IClientChannel 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 Arquitetura de cliente WCF.

Partilhar via