Noções básicas sobre o código do cliente gerado

Artigo
03/02/2024

A ServiceModel Metadata Utility Tool (Svcutil.exe) gera código de cliente e um arquivo de configuração de aplicativo cliente para uso na criação de aplicativos cliente. Este tópico fornece um tour de exemplos de código gerado para cenários de contrato de serviço padrão. Para obter mais informações sobre como criar um aplicativo cliente usando o código gerado, consulte Visão geral do cliente WCF.

Descrição geral

Se você usar o Visual Studio para gerar tipos de cliente do Windows Communication Foundation (WCF) para seu projeto, normalmente não será necessário examinar o código de cliente gerado. Se você não estiver usando um ambiente de desenvolvimento que executa os mesmos serviços para você, você pode usar uma ferramenta como Svcutil.exe para gerar código de cliente e, em seguida, usar esse código para desenvolver seu aplicativo cliente.

Como Svcutil.exe tem várias opções que modificam as informações de tipo geradas, este tópico não discute todos os cenários. No entanto, as seguintes tarefas padrão envolvem a localização do código gerado:

Identificação de interfaces de contratos de serviços.
Identificando a classe de cliente WCF.
Identificação de tipos de dados.
Identificação de contratos de retorno de chamada para serviços duplex.
Identificação da interface do canal do contrato de serviço auxiliar.

Localizando interfaces de contrato de serviço

Para localizar as interfaces que modelam contratos de serviço, procure interfaces marcadas com o System.ServiceModel.ServiceContractAttribute atributo. Muitas vezes, esse atributo pode ser difícil de localizar com uma leitura rápida devido à presença de outros atributos e às propriedades explícitas definidas no próprio atributo. Lembre-se de que a interface do contrato de serviço e a interface do contrato do cliente são dois tipos diferentes. O exemplo de código a seguir mostra o contrato de serviço original.

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

O exemplo de código a seguir mostra o mesmo contrato de serviço gerado por Svcutil.exe.

[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);
}

Você pode usar a interface do contrato de serviço gerado junto com a System.ServiceModel.ChannelFactory classe para criar um objeto de canal WCF com o qual invocar operações de serviço. Para obter mais informações, consulte Como usar o ChannelFactory.

Localizando classes de cliente WCF

Para localizar a classe de cliente WCF que implementa o contrato de serviço que você deseja usar, procure uma extensão de , onde o parâmetro type é a interface do contrato de System.ServiceModel.ClientBase<TChannel>serviço que você localizou anteriormente e que estende essa interface. O exemplo de código a seguir mostra a ClientBase<TChannel> classe do tipo ISampleService.

[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);
    }
}

Você pode usar essa classe de cliente WCF criando uma nova instância dela e chamando os métodos que ela implementa. Esses métodos invocam a operação de serviço com a qual ele foi projetado e configurado para interagir. Para obter mais informações, consulte Visão geral do cliente WCF.

Nota

Quando SvcUtil.exe gera uma classe de cliente WCF, adiciona uma DebuggerStepThroughAttribute à classe de cliente que impede os depuradores de percorrer a classe de cliente WCF.

Localizando tipos de dados

Para localizar tipos de dados no código gerado, o mecanismo mais básico é identificar o nome do tipo especificado em um contrato e pesquisar o código para essa declaração de tipo. Por exemplo, o contrato a seguir especifica que o SampleMethod pode retornar uma falha SOAP do tipo microsoft.wcf.documentation.SampleFault.

[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);

A pesquisa SampleFault localiza a seguinte declaração de tipo.

[assembly: System.Runtime.Serialization.ContractNamespaceAttribute(
  "http://microsoft.wcf.documentation",
  ClrNamespace = "microsoft.wcf.documentation"
)]
namespace microsoft.wcf.documentation
{
    using System.Runtime.Serialization;

    [System.CodeDom.Compiler.GeneratedCodeAttribute("System.Runtime.Serialization", "3.0.0.0")]
    [System.Runtime.Serialization.DataContractAttribute()]
    public partial class SampleFault : object, System.Runtime.Serialization.IExtensibleDataObject
    {
        private System.Runtime.Serialization.ExtensionDataObject extensionDataField;
        private string FaultMessageField;

        public System.Runtime.Serialization.ExtensionDataObject ExtensionData
        {
            get
            {
                return this.extensionDataField;
            }
            set
            {
                this.extensionDataField = value;
            }
        }

        [System.Runtime.Serialization.DataMemberAttribute()]
        public string FaultMessage
        {
            get
            {
                return this.FaultMessageField;
            }
            set
            {
                this.FaultMessageField = value;
            }
        }
    }
}

Neste caso, o tipo de dados é o tipo de detalhe lançado por uma exceção específica no cliente, um FaultException<TDetail> onde o parâmetro de tipo de detalhe é microsoft.wcf.documentation.SampleFault. Para obter mais informações sobre tipos de dados, consulte Especificando transferência de dados em contratos de serviço. Para obter mais informações sobre como lidar com exceções em clientes, consulte Enviando e recebendo falhas.

Localizando contratos de retorno de chamada para serviços duplex

Se você localizar um contrato de serviço para o qual a interface do contrato especifica um valor para a ServiceContractAttribute.CallbackContract propriedade, esse contrato especifica um contrato duplex. Os contratos duplex exigem que o aplicativo cliente crie uma classe de retorno de chamada que implemente o contrato de retorno de chamada e passe uma instância dessa classe para o System.ServiceModel.DuplexClientBase<TChannel> ou System.ServiceModel.DuplexChannelFactory<TChannel> usado para se comunicar com o serviço. Para obter mais informações sobre clientes duplex, consulte Como acessar serviços com um contrato duplex.

O contrato a seguir especifica um contrato de retorno de chamada do tipo SampleDuplexHelloCallback.

[System.ServiceModel.ServiceContractAttribute(
  Namespace="http://microsoft.wcf.documentation",
  ConfigurationName="SampleDuplexHello",
  CallbackContract=typeof(SampleDuplexHelloCallback),
  SessionMode=System.ServiceModel.SessionMode.Required
)]
public interface SampleDuplexHello
{
  [System.ServiceModel.OperationContractAttribute(
      IsOneWay=true,
      Action="http://microsoft.wcf.documentation/SampleDuplexHello/Hello"
    )]
    void Hello(string greeting);
  }

    <System.ServiceModel.OperationContractAttribute(IsOneWay:=True, _
        Action:="http://microsoft.wcf.documentation/SampleDuplexHello/Hello")> _
    Sub Hello(ByVal greeting As String)
End Interface 'SampleDuplexHello

A pesquisa desse contrato de retorno de chamada localiza a seguinte interface que o aplicativo cliente deve implementar.

  [System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public interface SampleDuplexHelloCallback
{
  [System.ServiceModel.OperationContractAttribute(
      IsOneWay=true,
      Action="http://microsoft.wcf.documentation/SampleDuplexHello/Reply"
    )]
    void Reply(string responseToGreeting);
  }

<System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")>  _
Public Interface SampleDuplexHelloCallback
    <System.ServiceModel.OperationContractAttribute( _
        IsOneWay:=True, _
        Action:="http://microsoft.wcf.documentation/SampleDuplexHello/Reply")> _
    Sub Reply(ByVal responseToGreeting As String)
End Interface 'SampleDuplexHelloCallback

Localizando interfaces de canal de contrato de serviço

Ao usar a ChannelFactory classe com uma interface de contrato de serviço, você deve transmitir para a System.ServiceModel.IClientChannel interface para abrir, fechar ou anular explicitamente o canal. Para facilitar o trabalho, a ferramenta Svcutil.exe também gera uma interface auxiliar que implementa a interface do contrato de serviço e IClientChannel permite que você interaja com a infraestrutura do canal do cliente sem ter que transmitir. O código a seguir mostra a definição de um canal de cliente auxiliar que implementa o contrato de serviço anterior.

[System.CodeDom.Compiler.GeneratedCodeAttribute("System.ServiceModel", "3.0.0.0")]
public interface ISampleServiceChannel : ISampleService, System.ServiceModel.IClientChannel
{
}

Consulte também

Visão geral do cliente WCF

Partilhar via