Introducción al cliente WCF

En esta sección se describe qué hacen las aplicaciones cliente, cómo configurar, crear y usar un cliente de Windows Communication Foundation (WCF) y cómo proteger las aplicaciones cliente.

Uso de objetos de cliente WCF

Una aplicación cliente es una aplicación administrada que usa un cliente WCF para comunicarse con otra aplicación. La creación de una aplicación cliente para un servicio WCF requiere los pasos siguientes:

1. Obtenga el contrato de servicio, las vinculaciones y la información de dirección para un punto de conexión de servicio.

2. Cree un cliente WCF con esa información.

3. Llame a las operaciones.

4. Cierre el objeto de cliente WCF.

En las secciones siguientes se describen estos pasos y se proporcionan breves introduccións a los siguientes problemas:

• Control de errores

• Configuración y protección de clientes.

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

• Llamada asincrónica a los servicios.

• Llamar a servicios mediante canales de cliente.

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

En WCF, los servicios y los clientes modelan contratos mediante atributos administrados, interfaces y métodos. Para conectarse a un servicio en una aplicación cliente, debe obtener la información de tipo del contrato de servicio. Normalmente, se obtiene información de tipo para el contrato de servicio mediante la Herramienta de utilidad de metadatos de ServiceModel (Svcutil.exe).. La utilidad descarga metadatos del servicio, lo convierte en un archivo de código fuente administrado en el idioma que prefiera y crea un archivo de configuración de aplicación cliente que puede usar para configurar el objeto de cliente WCF. Por ejemplo, si va a crear un objeto de cliente WCF para invocar un MyCalculatorServicey sabe que los metadatos de ese servicio se publican en http://computerName/MyCalculatorService/Service.svc?wsdl, en el ejemplo de código siguiente se muestra cómo usar Svcutil.exe para obtener un ClientCode.vb archivo que contenga el contrato de servicio 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 usar para crear un objeto de cliente WCF. Puede usar el archivo de configuración para configurar el objeto de cliente para conectarse correctamente al servicio .

Para obtener un ejemplo de este proceso, vea How to: Create a Client. Para obtener más información sobre los contratos, consulte Contratos.

Crear un objeto de cliente WCF

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

También puede usar objetos de canal de cliente WCF para conectarse a servicios y usarlos. Para obtener más información, consulte Arquitectura de cliente WCF.

Crear un nuevo objeto WCF

Para ilustrar el uso de una ClientBase<TChannel> clase, suponga que se ha generado el siguiente contrato de servicio simple a partir de una aplicación de servicio.

Nota:

Si usa Visual Studio para crear el cliente WCF, los objetos se cargan automáticamente en el explorador de objetos al agregar una referencia de servicio al proyecto.

[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<TChannel> y la interfaz del contrato de servicio ISampleService. En este caso, ese tipo de código tiene el siguiente aspecto:

[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 se puede crear como un objeto local mediante uno de los constructores, configurados y, a continuación, se usa para conectarse a un servicio del tipo ISampleService.

Se recomienda crear primero el objeto de cliente WCF y, a continuación, usarlo y cerrarlo dentro de un único bloque try/catch. No use la using instrucción (Using en Visual Basic) porque puede enmascarar excepciones en determinados modos de error. Para más información, consulte las secciones siguientes, así como Uso de Close y Abort para liberar los recursos del cliente WCF.

Contratos, vínculos y direcciones

Para poder crear un objeto de cliente WCF, debe configurar el objeto de cliente. En concreto, debe disponer de un punto de conexión de servicio que poder utilizar. Un punto de conexión es la combinación de un contrato de servicio, un enlace y una dirección. (Para obtener más información sobre los puntos de conexión, vea Puntos de conexión : direcciones, enlaces y contratos). Normalmente, esta información se encuentra en el <elemento endpoint> de un archivo de configuración de aplicación cliente, como la 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 mediante programación esta información.

Por ejemplo, un archivo de configuración generado para un ISampleService usado en los ejemplos anteriores contiene la siguiente información de punto de conexión.

<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 archivo de configuración especifica un punto de conexión de destino en el <client> elemento . Para obtener más información sobre el uso de varios puntos de conexión de destino, consulte los constructores ClientBase<TChannel> o ChannelFactory<TChannel>.

Llamadas a operaciones

Una vez que haya creado y configurado un objeto de cliente, cree un bloque try/catch, llame a operaciones de la misma manera que si el objeto fuera 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 y el canal subyacente se cierra cuando se recicla 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 tiene 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 operaciones mediante la creación de un objeto de cliente WCF y la llamada a sus métodos, como se muestra en el ejemplo de código siguiente. La apertura, llamada y cierre del objeto de cliente WCF se produce dentro de un único bloque try/catch. Para obtener más información, vea Obtener acceso a servicios mediante un cliente WCF y Usar Cerrar y 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();
}

Control de errores

Las excepciones pueden producirse en una aplicación cliente al abrir el canal de cliente subyacente (ya sea de manera explícita o automáticamente al llamar a una operación), al utilizar el objeto de cliente o canal para realizar operaciones, o al cerrar el canal de cliente subyacente. Se recomienda como mínimo que las aplicaciones esperen manejar posibles excepciones System.TimeoutException y System.ServiceModel.CommunicationException, además de cualquier objeto System.ServiceModel.FaultException que se produzca como resultado de errores SOAP devueltos por las operaciones. Los errores SOAP especificados en el contrato de operación se elevan a las aplicaciones cliente como un System.ServiceModel.FaultException<TDetail> donde el parámetro tipo es el tipo de detalle del error SOAP. Para obtener más información sobre cómo controlar las condiciones de error en una aplicación cliente, consulte Envío y recepción de errores. Para obtener un ejemplo completo, muestra cómo controlar los errores en un cliente, consulte Excepciones esperadas.

Configuración y protección de clientes

La configuración de un cliente comienza con la carga necesaria de la información del punto de conexión de destino para el objeto de cliente o canal, normalmente desde un archivo de configuración, aunque también puede cargar esta información mediante programación mediante el uso de los constructores y propiedades de cliente. Sin embargo, se requieren pasos de configuración adicionales para habilitar cierto comportamiento de cliente y para muchos escenarios de seguridad.

Por ejemplo, los requisitos de seguridad de los contratos de servicio se declaran en la interfaz de contrato de servicio y, si Svcutil.exe creó un archivo de configuración, ese archivo normalmente contiene una vinculación capaz de admitir los requisitos de seguridad del servicio. En algunos casos, sin embargo, puede ser necesaria más configuración de seguridad, como la configuración de credenciales de cliente. Para obtener información completa sobre la configuración de seguridad de los clientes WCF, consulte Protección de clientes.

Además, algunas modificaciones personalizadas se pueden habilitar en aplicaciones cliente, como comportamientos en tiempo de ejecución personalizados. Para obtener más información sobre cómo configurar un comportamiento de cliente personalizado, consulte Configuración de comportamientos de 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 se puede iniciar un canal con un objeto de devolución de llamada), para los fines de implementación y configuración se pueden considerar 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, puede controlar varios aspectos del comportamiento en 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, consulte Servicios dúplex. Para obtener un ejemplo completo, consulte Dúplex.

En equipos Windows XP que ejecutan Internet Information Services (IIS) 5.1, los clientes dúplex deben especificar una dirección base de cliente mediante la System.ServiceModel.WSDualHttpBinding clase o se produce una excepción. En el ejemplo de código siguiente se muestra cómo hacerlo en el 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/")

El código siguiente muestra cómo hacerlo en un archivo de configuración

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

Llamar a servicios de forma asincrónica

La decisión de cómo se llaman las operaciones depende completamente del desarrollador cliente. Esto se debe a que los mensajes que componen una operación se pueden asignar a métodos sincrónicos o asincrónicos cuando se expresan en código administrado. Por lo tanto, si desea compilar un cliente que llama a operaciones de forma asincrónica, puede usar Svcutil.exe para generar código de cliente asincrónico mediante la /async opción . Para más información, consulte Procedimiento para llamar a operaciones de servicio WCF de forma asincrónica.

Llamada a los servicios mediante canales de cliente WCF.

Los tipos de cliente WCF extienden ClientBase<TChannel>, que, a su vez, deriva de la interfaz System.ServiceModel.IClientChannel para exponer el sistema del canal subyacente. Puede invocar servicios utilizando el contrato del servicio de destino con la clase System.ServiceModel.ChannelFactory<TChannel>. Para obtener más información, consulte Arquitectura de cliente WCF.

Consulte también

• System.ServiceModel.ClientBase<TChannel>
• System.ServiceModel.ChannelFactory<TChannel>