Vue d’ensemble du client WCF

Cette section décrit ce que font les applications clientes, comment configurer, créer et utiliser un client Windows Communication Foundation (WCF) et comment sécuriser les applications clientes.

Utilisation d’objets client WCF

Une application cliente est une application managée qui utilise un client WCF pour communiquer avec une autre application. La création d’une application cliente pour un service WCF nécessite les étapes suivantes :

Obtenez le contrat de service, les liaisons et les informations d’adresse pour un point de terminaison de service.
Créez un client WCF à l’aide de ces informations.
Appelez les opérations.
Fermez l’objet client WCF.

Les sections suivantes décrivent 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.
Appel de services en utilisant des canaux clients.

Obtenir le contrat de service, les liaisons et les adresses

Dans WCF, les services et les clients modélisent des contrats à l’aide d’attributs managés, d’interfaces et de méthodes. Pour vous connecter à un service dans une application cliente, vous devez obtenir les informations de type pour le contrat de service. En règle générale, vous obtenez des informations de type pour le contrat de service à l’aide de l’outil utilitaire de métadonnées ServiceModel (Svcutil.exe). L’utilitaire télécharge les métadonnées à partir du service, les convertit en fichier de code source managé dans la langue 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 allez créer un objet client WCF pour appeler un MyCalculatorService, et que vous savez que les métadonnées de ce service sont publiées à l’adresse http://computerName/MyCalculatorService/Service.svc?wsdl, l’exemple de code suivant montre comment utiliser Svcutil.exe pour obtenir un fichier ClientCode.vb qui contient le contrat de service dans le 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 ensuite utiliser pour créer un objet client WCF. Vous pouvez utiliser le fichier de configuration pour configurer l’objet client pour qu’il se connecte correctement au service.

Pour obtenir un exemple de ce processus, consultez Guide pratique pour créer un client. Pour plus d’informations 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 un formulaire que le client peut utiliser pour communiquer avec le service distant. Les types de clients WCF implémentent le contrat de service cible. Par conséquent, lorsque vous en créez un et que vous le configurez, vous pouvez ensuite utiliser l’objet client directement pour appeler des opérations de service. Le runtime 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 en tant que valeurs de retour ou outref paramètres.

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

Création d’un objet WCF

Pour illustrer l’utilisation d’une ClientBase<TChannel> classe, supposons que le contrat de service simple suivant a été généré à partir d’une application de service.

Remarque

Si vous utilisez Visual Studio pour créer votre client WCF, les objets sont chargés automatiquement dans le navigateur 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 trouver le type qui étend ClientBase<TChannel> 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 en tant qu’objet local à l’aide de l’un des constructeurs, configurés, puis utilisés pour se connecter à un service du type ISampleService.

Il est recommandé de créer d’abord votre objet client WCF, puis de l’utiliser et de le fermer à l’intérieur d’un bloc try/catch unique. N’utilisez pas l’instruction using (Using en Visual Basic), car elle peut masquer les exceptions dans certains modes d’échec. Pour plus d’informations, consultez les sections suivantes ainsi que Utiliser Close et Abort pour libérer les ressources client WCF.

Contrats, liaisons et adresses

Avant de pouvoir créer un objet client WCF, vous devez configurer l’objet client. Plus précisément, il doit disposer d’un point de terminaison de service endpoint à 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 les points de terminaison, consultez Points de terminaison : Adresses, liaisons et contrats.) En règle générale, ces informations se trouvent dans l’élément <de point de terminaison> d’un fichier de configuration d’application cliente, comme celle générée par l’outil Svcutil.exe et sont chargées automatiquement lorsque vous créez votre objet client. Les deux types de clients WCF ont également des surcharges qui vous permettent de spécifier ces informations par programmation.

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

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

Ce fichier de configuration spécifie un point de terminaison cible dans l’élément <client> . Pour plus d’informations sur l’utilisation de plusieurs points de terminaison cibles, consultez les constructeurs ClientBase<TChannel> ou ChannelFactory<TChannel>.

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 le canal sous-jacent 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 disposez du 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 l’illustre l’exemple de code suivant. 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 WCF et Utiliser Fermer et abandonner pour libérer les ressources du client 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();
}

Gestion des erreurs

Les exceptions peuvent se produire dans une application cliente lors de l’ouverture du canal client sous-jacent (que ce soit explicitement ou automatiquement en appelant une opération), à l’aide du client ou de l’objet 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 envoyées aux applications clientes en tant System.ServiceModel.FaultException<TDetail> où le paramètre de type est le type de détail de l’erreur SOAP. Pour plus d’informations sur la gestion des conditions d’erreur dans une application cliente, consultez Envoi et réception d’erreurs. Pour obtenir un exemple complet, l’exemple montre comment gérer les erreurs dans un client, consultez Exceptions attendues.

Configuration et sécurisation des clients

La configuration d’un client commence par le chargement requis des informations de point de terminaison cible pour l’objet client ou canal, généralement à partir d’un fichier de configuration, bien que vous puissiez également charger ces informations par programmation à l’aide des constructeurs et propriétés clients. Toutefois, des étapes de configuration supplémentaires sont nécessaires pour activer certains comportements clients et pour de nombreux scénarios de sécurité.

Par exemple, les exigences de sécurité pour les contrats de service sont déclarées dans l’interface de contrat de service et, si Svcutil.exe créé un fichier de configuration, ce fichier contient généralement une liaison capable de prendre en charge les exigences de sécurité du service. Toutefois, dans certains cas, davantage de configuration de sécurité peut être nécessaire, par exemple la configuration des informations d’identification du client. Pour obtenir des informations complètes sur la configuration de la sécurité pour les clients WCF, consultez Sécurisation des clients.

En outre, certaines modifications personnalisées peuvent être activées dans les applications clientes, telles que les comportements d’exécution personnalisés. Pour plus d’informations sur la configuration d’un comportement client personnalisé, consultez Configuration des comportements des 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 que le service appelle en fonction des exigences du contrat. Bien que les objets de rappel ne soient pas des services complets (par exemple, vous ne pouvez pas lancer un canal avec un objet de rappel), à des fins d’implémentation et de configuration, ils peuvent être considérés comme un type de service.

Les clients des services duplex doivent :

Implémenter une classe de contrat de rappel.
Créez une instance de la classe d’implémentation du contrat de rappel et utilisez-la pour créer l’objet System.ServiceModel.InstanceContext que vous passez au constructeur client WCF.
Appeler des opérations et gérer les rappels d’opération.

Les objets clients WCF duplex fonctionnent comme leurs équivalents nonduplex, à l’exception qu’ils exposent les fonctionnalités nécessaires pour prendre en charge les rappels, y compris la configuration du service de rappel.

Par exemple, vous pouvez contrôler différents aspects du comportement du runtime d’objet de rappel à l’aide des propriétés de l’attribut System.ServiceModel.CallbackBehaviorAttribute sur la classe de rappel. Un autre exemple est l’utilisation de la System.ServiceModel.Description.CallbackDebugBehavior classe pour activer le retour d’informations d’exception aux services qui appellent l’objet de rappel. Pour plus d’informations, consultez Duplex Services. Pour obtenir un exemple complet, consultez Duplex.

Sur les ordinateurs Windows XP exécutant Internet Information Services (IIS) 5.1, les clients duplex doivent spécifier une adresse de base client à l’aide de la classe System.ServiceModel.WSDualHttpBinding, sinon une exception est levée. L’exemple de code suivant montre comment procéder dans le code.

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

Le code suivant montre comment procéder dans un fichier de configuration

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

Appeler les services de manière asynchrone

La façon dont les opérations sont appelées relève entièrement du développeur client. Cela est dû au fait que les messages qui composent une opération peuvent être mappés à des méthodes synchrones ou asynchrones lorsqu’elles sont exprimées dans du code managé. Par conséquent, si vous souhaitez créer un client qui appelle des opérations de manière asynchrone, vous pouvez utiliser Svcutil.exe pour générer du code client asynchrone à l’aide de l’option /async . Pour plus d’informations, consultez Guide pratique pour appeler des opérations de service de façon asynchrone.

Appels des services à l'aide des canaux clients WCF

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

Voir aussi

Last updated on 2025-06-20

Partager via