Compartir a través de

Introducción a un cliente WCF

  • Artículo

En esta sección se describe qué aplicaciones pueden configurar un cliente Windows Communication Foundation (WCF), cómo lo configuran, crean y utilizan, y cómo proteger las aplicaciones cliente.

Utilización de objetos cliente WCF

Una aplicación cliente es una aplicación administrada que utiliza un cliente WCF para comunicarse con otra aplicación. Para crear la aplicación cliente de un servicio WCF es necesario seguir los pasos siguientes:

  1. Obtenga la información del contrato de servicio, el enlace y la dirección del extremo del servicio.

  2. Cree un cliente WCF utilizando dicha información.

  3. Llame a las operaciones.

  4. Cierre el objeto de cliente WCF.

Las siguientes secciones explican estos pasos y proporcionan una breve introducción a las siguientes cuestiones:

  • Control de errores

  • Configuración y protección de los clientes.

  • Creación de objetos de devolución de llamada para los servicios dúplex.

  • Llamada asincrónica a los servicios.

  • Llamada a los servicios mediante los canales cliente.

Obtención del contrato de servicios, los enlaces y las direcciones

En WCF, los servicios y clientes modelan los contratos utilizando los atributos, interfaces y métodos administrados. Para conectar con un servicio en una aplicación cliente, es necesario obtener la información del tipo de contrato de servicios. Normalmente, esto se consigue mediante Herramienta de utilidad de metadatos de ServiceModel (Svcutil.exe), que descarga los metadatos del servicio, los convierte en un archivo de código fuente administrado con el lenguaje elegido, y crea un archivo de configuración de aplicación cliente que puede utilizarse para configurar el objeto de cliente WCF. Por ejemplo, si se crea un objeto de cliente WCF para invocar un MyCalculatorService, y se sabe que los metadatos de ese servicio están publicados en http://computerName/MyCalculatorService/Service.svc?wsdl, el siguiente ejemplo de código muestra cómo utilizar Svcutil.exe para obtener un archivo ClientCode.vb que contenga el contrato de servicios en código administrado.

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

Puede compilar este código de contrato en la aplicación cliente, o en otro ensamblado que la aplicación cliente puede utilizar para crear un objeto de cliente WCF. Puede utilizar el archivo de configuración y configurar el objeto de cliente para conectarse correctamente con el servicio.

Para obtener un ejemplo de este proceso, vea Creación de un cliente de Windows Communication Foundation. Para obtener información completa acerca de los contratos, vea Contratos.

Creación de un objeto de cliente de WCF

Un cliente WCF es un objeto local que representa un servicio WCF en un formulario que el cliente puede utilizar para la comunicación con el servicio remoto. Los tipos de cliente WCF implementan el contrato de servicio de destino, de modo que al crear uno y configurarlo, puede utilizarse directamente el objeto de cliente para invocar las operaciones del servicio. El tiempo de ejecución WCF convierte las llamadas al método en mensajes, los envía al servicio, realiza escuchas para la respuesta, y devuelve esos valores al objeto de cliente WCF como valores devueltos, parámetros out o ref.

También pueden utilizarse los objetos de canal de cliente WCF para la conexión con los servicios y la utilización de los mismos. Para obtener información detallada, vea Arquitectura de cliente.

Creación de un nuevo objeto WCF

Para mostrar la utilización de una clase ClientBase, supongamos que el siguiente contrato de servicio simple se ha generado a partir de una aplicación de servicio.

ms735103.note(es-es,VS.100).gifNota:
Si se utiliza Visual Studio para crear el cliente WCF, cuando se agrega una referencia de servicio al proyecto, los objetos se cargan automáticamente en el examinador de objetos. 

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

Si no utiliza Visual Studio, examine el código de contrato generado para encontrar el tipo que extiende ClientBase, y el ISampleServicede la interfaz del contrato de servicio. En este caso, ese tipo es similar al código siguiente:

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

Esta clase puede crearse como un objeto local, mediante uno de los constructores, configurarse y, a continuación, utilizarse para la conexión con un servicio del tipo ISampleService.

Se recomienda crear primero el objeto de cliente WCF, y, a continuación, utilizarlo y cerrarlo dentro de un único bloque try/catch. No debe utilizarse la instrucción using (Using en Visual Basic) porque puede enmascarar excepciones en ciertos modos de error. Para obtener más información, vea las siguientes secciones, así como Evitar problemas mediante una declaración de instrucción.

Contratos, enlaces y direcciones

Antes de poder crear un objeto de cliente WCF, éste debe configurarse. En concreto, debe disponer de un extremo de servicio que poder utilizar. Un extremo es la combinación de un contrato de servicio, un enlace y una dirección. (Para obtener más información sobre los extremos, vea Extremos: direcciones, enlaces y contratos). Normalmente, esta información se encuentra en el elemento <endpoint> de un archivo de configuración de la aplicación cliente, como el que genera la herramienta Svcutil.exe, y se carga automáticamente al crear el objeto de cliente. Ambos tipos de cliente WCF también tienen sobrecargas que permiten especificar esta información mediante programación.

Por ejemplo, un archivo de configuración generado para el ISampleService utilizado en los ejemplos anteriores, contiene la información de extremo siguiente.

<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="https://localhost:8080/SampleService" binding="wsHttpBinding"
                bindingConfiguration="WSHttpBinding_ISampleService" contract="ISampleService"
                name="WSHttpBinding_ISampleService">
            </endpoint>
        </client>
    </system.serviceModel>
</configuration>

Este archivo de configuración especifica un extremo de destino en el elemento <client>. Para obtener más información sobre la utilización de varios extremos de destino, vea System.ServiceModel.ClientBase.#ctor(System.String) o los constructores System.ServiceModel.ChannelFactory.#ctor(System.String).

Llamadas a operaciones

Una vez creado y configurado un objeto de cliente, cree un bloque try/catch, llame a las operaciones del mismo modo a como lo haría si el objeto fuese local, y cierre el objeto de cliente WCF. Cuando la aplicación cliente llama a la primera operación, WCF abre automáticamente el canal subyacente, que se cierra al reciclar el objeto. (De manera alternativa, también puede abrir y cerrar explícitamente el canal antes o después de llamar a otras operaciones).

Por ejemplo, si posee el siguiente contrato de servicio:

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

Puede llamar a las operaciones mediante la creación de un objeto de cliente WCF y la llamada a sus métodos, como muestra el ejemplo de código siguiente. Tenga en cuenta que la apertura, llamada y cierre del objeto de cliente WCF tiene lugar en un bloque try/catch único. Para obtener más información, vea Acceso a los servicios utilizando un cliente y Evitar problemas mediante una declaración de instrucción.

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

Control de errores

Las excepciones pueden producirse en una aplicación cliente cuando se abre el canal de cliente subyacente (explícita o automáticamente mediante la llamada a una operación), se utiliza el cliente u objeto de canal para llamar a las operaciones, o se cierra el canal de cliente subyacente. Se recomienda como mínimo que las aplicaciones prevean administrar posibles System.TimeoutException y las excepciones System.ServiceModel.CommunicationException, además de cualquier objeto System.ServiceModel.FaultException iniciado como resultado de los errores de SOAP devueltos por las operaciones. Los errores de SOAP especificados en el contrato de operación se elevan a las aplicaciones cliente como System.ServiceModel.FaultException, donde el parámetro de tipo es el tipo de detalle del error de SOAP. Para obtener más información sobre la administración de las condiciones de error de aplicación cliente, vea Envío y recepción de errores. Para obtener un ejemplo completo que muestre cómo controlar los errores de, vea Excepciones esperadas.

Configuración y protección de clientes.

La configuración de un cliente se inicia con la carga de información de extremo de destino necesaria para el cliente u objeto de canal, normalmente desde un archivo de configuración, aunque también puede cargarse esta información mediante programación utilizando los constructores y propiedades de cliente. No obstante, son necesarios pasos de configuración adicionales que habiliten cierto comportamiento del cliente y diferentes escenarios de seguridad.

Por ejemplo, los requisitos de seguridad para los contratos de servicios se declaran en la interfaz del contrato de servicio; si Svcutil.exe creó un archivo de configuración, ese archivo contiene, normalmente, un enlace capaz de admitir los requisitos de seguridad del servicio. En algunos casos, sin embargo, puede ser necesaria una mayor configuración de seguridad, como la configuración de credenciales de cliente. Para obtener información completa acerca de la configuración de seguridad para los clientes WCF, vea Protección de clientes.

Además, algunas modificaciones personalizadas pueden habilitarse en las aplicaciones cliente, por ejemplo, los comportamientos de tiempo de ejecución personalizados. Para obtener más información sobre la configuración de un comportamiento de cliente personalizado, vea Configuración de los comportamientos del cliente.

Creación de objetos de devolución de llamada para servicios dúplex.

Los servicios dúplex especifican un contrato de devolución de llamada que la aplicación cliente debe implementar para proporcionar un objeto de devolución de llamada, y que el servicio realice las llamadas según los requisitos del contrato. Aunque los objetos de devolución de llamada no son servicios completos (por ejemplo, no puede iniciar un canal con un objeto de devolución de llamada), en lo que respecta la implementación y la configuración pueden concebirse como un tipo de servicio.

Los clientes de servicios dúplex deben:

  • Implementar una clase de contrato de devolución de llamada.

  • Crear una instancia de la clase de implementación de contrato de devolución de llamada, y utilizarla para crear el objeto System.ServiceModel.InstanceContext que se pasa al constructor de cliente WCF.

  • Invocar operaciones y controlar las devoluciones de llamada de la operación.

Los objetos de cliente WCF dúplex funcionan como sus homólogos no dúplex, salvo que exponen la funcionalidad necesaria para admitir las devoluciones de llamada, incluida la configuración del servicio de devolución de llamada.

Por ejemplo, pueden controlarse distintos aspectos del comportamiento del tiempo de ejecución del objeto de devolución de llamada mediante las propiedades del atributo System.ServiceModel.CallbackBehaviorAttribute, en la clase de devolución de llamada. Otro ejemplo es el uso de la clase System.ServiceModel.Description.CallbackDebugBehavior para habilitar el retorno de información de excepción a los servicios que llaman al objeto de devolución de llamada. Para obtener más información, vea Servicios dúplex. Para obtener un ejemplo completo, vea Dúplex.

En los equipos de Windows XP que ejecutan Internet Information Services (IIS) 5.1, los clientes dúplex deben especificar una dirección base de cliente utilizando la clase System.ServiceModel.WSDualHttpBinding, o se iniciará una excepción. En el ejemplo de código siguiente se muestra cómo realizar esta especificación en el código.

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

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

El código siguiente muestra cómo realizar esta especificación en un archivo de configuración

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

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

Llamada a servicios de manera asincrónica.

La manera cómo se realizan las llamadas a las operaciones depende del desarrollador cliente. La razón es que los mensajes que constituyen una operación pueden asignarse a métodos sincrónicos o asincrónicos cuando se expresan en código administrado. Por consiguiente, si desea crear un cliente que llama a las operaciones de manera asincrónica, puede utilizar Svcutil.exe para generar código de cliente asincrónico mediante la opción /async. Para obtener más información, vea Cómo llamar a operaciones del servicio WCF de forma asincrónica.

Llamada a los servicios mediante canales de cliente WCF.

Los tipos de cliente WCF extienden ClientBase, que, a su vez, deriva de la interfaz System.ServiceModel.IClientChannel para exponer el sistema del canal subyacente. Puede invocar los servicios utilizando el contrato de servicios de destino con la clase System.ServiceModel.ChannelFactory. Para obtener información detallada, vea Arquitectura de cliente.

Vea también

Referencia

System.ServiceModel.ClientBase
System.ServiceModel.ChannelFactory