Vue d'ensemble d'un client WCF

  • Article

Cette section décrit le fonctionnement des applications clientes, comment configurer, créer et utiliser un client Windows Communication Foundation (WCF), et comment sécuriser des applications clientes.

Utilisation des objets clients WCF

Une application cliente est une application managée qui utilise un client WCF pour communiquer avec une autre application. Pour créer une application cliente destinée à un service WCF, procédez comme suit :

  1. Obtenez le contrat de service, les informations de liaison et d'adresse pour un point de terminaison de service.

  2. Créez un client WCF à l'aide de ces informations.

  3. Appelez les opérations.

  4. Fermez l'objet client WCF.

Les sections suivantes traitent de ces étapes et fournissent de brèves introductions aux problèmes suivants :

  • Gestion des erreurs.

  • Configuration et sécurisation des clients.

  • Création d'objets de rappel pour les services duplex.

  • Appels des services de façon asynchrone..

  • Appels des services à l'aide de canaux clients.

Obtenir le contrat de service, les liaisons et les adresses

Dans WCF, les services et les clients modèlent des contrats qui utilisent des attributs, des interfaces et des méthodes managés. Pour se connecter à un service dans une application cliente, vous devez obtenir les informations de type pour le contrat de service. En général, cette opération s'effectue à l'aide de l'Outil Service Model Metadata Tool (Svcutil.exe) qui télécharge les métadonnées à partir du service, les convertit en un fichier de code source managé dans le langage de votre choix et crée un fichier de configuration d'application cliente que vous pouvez utiliser pour configurer votre objet client WCF. Par exemple, si vous devez créer un objet client WCF pour appeler un MyCalculatorService, et que vous savez que les métadonnées pour ce service sont publiées à l'adresse http://computerName/MyCalculatorService/Service.svc?wsdl, l'exemple de code suivant indique comment utiliser Svcutil.exe pour obtenir un fichier ClientCode.vb qui contient le contrat de service en code managé.

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

Vous pouvez compiler ce code de contrat dans l'application cliente ou dans un autre assembly que l'application cliente peut utiliser ensuite pour créer un objet client WCF. Vous pouvez utiliser le fichier de configuration pour configurer l'objet client pour se connecter correctement au service.

Pour obtenir un exemple de ce processus, consultez Comment : créer un client Windows Communication Foundation. Pour des informations plus complètes sur les contrats, consultez Contrats.

Créer un objet client WCF

Un client WCF est un objet local qui représente un service WCF sous une forme que le client peut utiliser pour communiquer avec le service distant. Les types de clients WCF implémentent le contrat de service cible, donc lorsque vous en créez un et que vous le configurez, vous pouvez utiliser ensuite directement l'objet client pour appeler des opérations de service. L'exécution WCF convertit les appels de méthode en messages, les envoie au service, écoute la réponse et retourne ces valeurs à l'objet client WCF comme valeurs de retour ou paramètres out ou ref.

Vous pouvez également utiliser les objets de canal de client WCF pour vous connecter et utiliser les services. Pour plus d'informations, consultez Architecture du client.

Création d'un nouvel objet WCF

Pour illustrer l'utilisation d'une classe ClientBase, supposons que le contrat de service simple suivant a été généré depuis une application de service.

ms735103.note(fr-fr,VS.100).gifRemarque :
Si vous utilisez Visual Studio pour créer votre client WCF, les objets sont chargés automatiquement dans l'Explorateur d'objets lorsque vous ajoutez une référence de service à votre projet. 

[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 vous n'utilisez pas Visual Studio, examinez le code de contrat généré pour rechercher le type qui étend ClientBase et l'interface de contrat de service ISampleService. Dans ce cas, ce type ressemble au code suivant :

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

Cette classe peut être créée comme un objet local à l'aide de l'un des constructeurs, elle peut être configurée, puis utilisée pour se connecter à un service du type ISampleService.

Il est recommandé de commencer par créer votre objet client WCF, puis de l'utiliser et de l'insérer dans un bloc try/catch unique. Vous ne devez pas utiliser l'instruction using (Using dans Visual Basic) parce qu'elle peut masquer des exceptions dans certains modes d'échec. Pour plus d'informations, consultez consultez les sections suivantes ainsi que Avoiding Problems with the Using Statement.

Contrats, liaisons et adresses

Avant de pouvoir créer un objet client WCF, vous devez le configurer. En particulier, celui-ci doit avoir un point de terminaison de service à utiliser. Un point de terminaison est la combinaison d'un contrat de service, d'une liaison et d'une adresse. (Pour plus d'informations sur le sujet suivant les points de terminaison, consultez Points de terminaison : adresses, liaisons et contrats.) En général, ces informations sont localisées dans l'élément <endpoint> dans un fichier de configuration d'application cliente, tel que celui généré par l'outil Svcutil.exe, et sont chargées automatiquement lorsque vous créez votre objet client. Les deux types clients WCF possèdent aussi des surcharges qui vous permettent de spécifier ces informations par programme.

Par exemple, un fichier de configuration généré pour un ISampleService utilisé dans les exemples précédents contient les informations suivantes sur le point de terminaison.

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

Ce fichier de configuration spécifie un point de terminaison cible dans l'élément <client>. Pour plus d'informations sur le sujet suivant l'utilisation de plusieurs points de terminaison cibles, consultez les constructeurs System.ServiceModel.ClientBase.#ctor(System.String) ou System.ServiceModel.ChannelFactory.#ctor(System.String).

Opérations appelantes

Une fois que vous avez créé et configuré un objet client, créez un bloc try/catch, appelez les opérations de la même façon que si l'objet était local et fermez l'objet client WCF. Lorsque l'application cliente appelle la première opération, WCF ouvre automatiquement le canal sous-jacent, et ce canal est fermé lorsque l'objet est recyclé. (Vous pouvez également ouvrir et fermer explicitement le canal avant ou après l'appel des autres opérations.)

Par exemple, si vous avez le contrat de service suivant :

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

Vous pouvez appeler des opérations en créant un objet client WCF et en appelant ses méthodes, comme illustré dans l'exemple de code suivant. Notez que l'ouverture, l'appel et la fermeture de l'objet client WCF se produisent dans un bloc try/catch unique. Pour plus d'informations, consultez Accès aux services à l'aide d'un client et Avoiding Problems with the Using Statement.

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

Gestion des erreurs

Des exceptions peuvent se produire dans une application cliente lors de l'ouverture du canal client sous-jacent (en appelant explicitement ou automatiquement une opération), lors de l'utilisation de l'objet client ou de canal pour appeler des opérations, ou lors de la fermeture du canal client sous-jacent. Il est recommandé que les applications gèrent au minimum les exceptions System.TimeoutException et System.ServiceModel.CommunicationException possibles en plus de tous les objets System.ServiceModel.FaultException levés suite aux erreurs SOAP retournées par les opérations. Les erreurs SOAP spécifiées dans le contrat d'opération sont levées aux applications clientes sous la forme d'une System.ServiceModel.FaultException où le paramètre de type représente le type de détail de l'erreur SOAP. Pour plus d'informations sur le sujet suivant la gestion des conditions d'erreur dans une application cliente, consultez Envoi et réception des erreurs. Pour un exemple complet illustrant comment gérer des erreurs dans un client, consultez Expected Exceptions.

Configuration et sécurisation des clients

La configuration d'un client démarre par le chargement nécessaire des informations de point de terminaison cibles pour l'objet client ou de canal, généralement depuis un fichier de configuration, même s'il est possible aussi de charger ces informations par programme à l'aide des constructeurs et des propriétés du client. Toutefois, des étapes de configuration supplémentaires sont nécessaires pour activer certain comportement client et pour de nombreux scénarios de sécurité.

Par exemple, les conditions de sécurité pour les contrats de service sont déclarées dans l'interface de contrat de service, et si Svcutil.exe a créé un fichier de configuration, ce fichier contient généralement une liaison qui peut prendre en charge les spécifications de sécurité du service. Dans certains cas, toutefois, davantage de configuration de sécurité peut être requis, tel que configurer des informations d'identification du client. Pour des informations complètes sur la configuration de sécurité pour les clients WCF, consultez Sécurisation des clients.

De plus, certaines modifications personnalisées peuvent être activées dans des applications clientes, telles que les comportements d'exécution personnalisés. Pour plus d'informations sur le sujet suivant la manière de configurer un comportement client personnalisé, consultez Configuration des comportements clients.

Création d'objets de rappel pour les services duplex

Les services duplex spécifient un contrat de rappel que l'application cliente doit implémenter afin de fournir un objet de rappel pour le service à appeler selon les spécifications du contrat. Bien que les objets de rappel ne soient pas des services complets (par exemple, vous ne pouvez pas initialiser de canal avec un objet de rappel), pour les besoins de l'implémentation et de la configuration ils peuvent être considérés comme un type de service.

Les clients de services duplex doivent :

  • Implémenter une classe de contrat de rappel.

  • Créer une instance de la classe d'implémentation du contrat de rappel et l'utiliser pour créer l'objet System.ServiceModel.InstanceContext que vous passez au constructeur client WCF.

  • Appeler des opérations et traiter des rappels d'opération.

Les objets clients WCF duplex fonctionnent comme leurs équivalents non-duplex, sauf qu'ils exposent les fonctionnalités nécessaire pour prendre en charge les rappels, y compris la configuration du service de rappel.

Par exemple, vous pouvez contrôler différents aspects de comportement à l'exécution de l'objet de rappel en utilisant des propriétés de l'attribut System.ServiceModel.CallbackBehaviorAttribute sur la classe de rappel. Un autre exemple est l'utilisation de la classe System.ServiceModel.Description.CallbackDebugBehavior pour permettre le retour d'informations sur les exceptions aux services qui appellent l'objet de rappel. Pour plus d'informations, consultez Services duplex. Pour un exemple complet, consultez Duplex.

Sur les ordinateurs Windows XP qui exécutent les services IIS (Internet Information Services) 5.1, les clients duplex doivent spécifier une adresse de base cliente à l'aide de la classe System.ServiceModel.WSDualHttpBinding ou une exception est levée. L'exemple de code suivant montre comment procéder.

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/");

Le code suivant montre comment effectuer cette opération dans un fichier de configuration

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

Appels des services de façon asynchrone.

Le mode d'appel des opérations dépend entièrement du développeur du client. En effet, les messages qui composent une opération peuvent être mappés aux méthodes synchrones ou asynchrones lorsqu'ils sont exprimés dans le code managé. Par conséquent, si vous souhaitez générer un client qui appelle des opérations de façon asynchrone, vous pouvez utiliser Svcutil.exe pour générer le code client asynchrone à l'aide de l'option /async. Pour plus d'informations, consultez Comment : appeler des opérations de service WCF de façon asynchrone.

Appels des services à l'aide des canaux clients WCF

Les types clients WCF étendent ClientBase qui dérive de l'interface System.ServiceModel.IClientChannel pour exposer le système de canaux sous-jacent. Vous pouvez appeler des services à l'aide du contrat de service cible avec la classe System.ServiceModel.ChannelFactory. Pour plus d'informations, consultez Architecture du client.

Voir aussi

Référence

System.ServiceModel.ClientBase
System.ServiceModel.ChannelFactory