Accès aux services à l'aide d'un clientAccessing Services Using a Client

Les applications clientes doivent créer, configurer et utiliser des objets de canal ou client WCF pour communiquer avec les services.Client applications must create, configure, and use WCF client or channel objects to communicate with services. La rubrique vue d’ensemble du client WCF fournit une vue d’ensemble des objets et des étapes nécessaires à la création d’objets client et de canal de base et à leur utilisation.The WCF Client Overview topic provides an overview of the objects and steps involved in creating basic client and channel objects and using them.

Cette rubrique fournit des informations détaillées sur certains aspects liés aux applications clientes et aux objets de client et de canal qui peuvent être utiles selon votre scénario.This topic provides in-depth information about some of the issues with client applications and client and channel objects that may be useful depending upon your scenario.

Vue d’ensembleOverview

Cette rubrique décrit le comportement et les problèmes liés aux éléments suivants :This topic describes behavior and issues relating to:

  • durées de vie de session et de canal ;Channel and session lifetimes.

  • gestion des exceptions ;Handling exceptions.

  • présentation des problèmes de blocage ;Understanding blocking issues.

  • initialisation de canaux de manière interactive.Initializing channels interactively.

Durées de vie de session et de canalChannel and Session Lifetimes

Les applications Windows Communication Foundation (WCF) incluent deux catégories de canaux, de datagrammes et de sessions.Windows Communication Foundation (WCF) applications includes two categories of channels, datagram and sessionful.

Un canal de datagramme est un canal dans lequel tous les messages sont non corrélés.A datagram channel is a channel in which all messages are uncorrelated. Avec un canal de datagramme, si une opération d'entrée ou de sortie échoue, l'opération suivante n'est en général pas affectée et le même canal peut être réutilisé.With a datagram channel, if an input or output operation fails, the next operation is typically unaffected, and the same channel can be reused. Pour cette raison, les canaux de datagramme ne subissent généralement pas de défaillance.Because of this, datagram channels typically do not fault.

Les canaux de session , toutefois, sont des canaux avec une connexion à l’autre point de terminaison.Sessionful channels, however, are channels with a connection to the other endpoint. Les messages dans une session d'un côté sont toujours en corrélation avec la même session de l'autre côté.Messages in a session on one side are always correlated with the same session on the other side. De plus, les deux participants d'une session doivent s'entendre sur le fait que les spécifications de leur conversation ont été satisfaites pour que cette session soit considérée comme réussie.In addition, both participants in a session must agree that the requirements of their conversation were met for that session to be considered successful. S'ils ne peuvent se mettre d'accord, le canal de session peut subir une défaillance.If they cannot agree, the sessionful channel may fault.

Ouvrir des clients explicitement ou implicitement en appelant la première opération.Open clients explicitly or implicitly by calling the first operation.

Notes

Le fait de tenter de détecter de manière explicite des canaux de session défaillants est en général inutile, car le moment où vous en êtes informé dépend de l'implémentation de session.Trying to explicitly detect faulted sessionful channels is not typically useful, because when you are notified depends upon the session implementation. Par exemple, étant donné que le System.ServiceModel.NetTcpBinding (avec la session fiable désactivée) est à la surface de la session de la connexion TCP, si vous écoutez l'événement ICommunicationObject.Faulted sur le service ou le client, vous recevrez sans doute rapidement une notification en cas de panne réseau.For example, because the System.ServiceModel.NetTcpBinding (with the reliable session disabled) surfaces the session of the TCP connection, if you listen to the ICommunicationObject.Faulted event on the service or the client you are likely to be notified quickly in the event of a network failure. Mais les sessions fiables (établies par des liaisons dans lesquelles le System.ServiceModel.Channels.ReliableSessionBindingElement est activé) sont conçues pour isoler les services des petites pannes réseau.But reliable sessions (established by bindings in which the System.ServiceModel.Channels.ReliableSessionBindingElement is enabled) are designed to insulate services from small network failures. Si la session peut être rétablie dans un délai raisonnable, la même liaison (configuré pour des sessions fiables) risque de ne subir une défaillance que longtemps après l'interruption.If the session can be reestablished within a reasonable period of time, the same binding—configured for reliable sessions—might not fault until the interruption continued for a longer period of time.

La plupart des liaisons fournies par le système (qui exposent des canaux à la couche Application) utilisent des sessions par défaut, ce qui n'est pas le cas du System.ServiceModel.BasicHttpBinding.Most of the system-provided bindings (which expose channels to the application layer) use sessions by default, but the System.ServiceModel.BasicHttpBinding does not. Pour plus d’informations, consultez utilisation de sessions.For more information, see Using Sessions.

Utilisation correcte des sessionsThe Proper Use of Sessions

Les sessions offrent un moyen de savoir si l'intégralité de l'échange de messages a été effectué et si les deux côtés l'ont considéré réussi.Sessions provide a way to know if the entire message exchange is complete, and if both sides considered it successful. Il est recommandé qu'une application appelante ouvre le canal, l'utilise et le ferme à l'intérieur d'un bloc try.It is recommended that a calling application open the channel, use it, and close the channel inside one try block. Si un canal de session est ouvert, que la méthode ICommunicationObject.Close est appelée une fois et que cet appel est retourné avec succès, cela signifie que la session a réussi.If a session channel is open, and the ICommunicationObject.Close method is called once, and that call returns successfully, then the session was successful. Le terme « réussi » dans ce cas signifie que toutes les garanties de remise spécifiées par la liaison ont été satisfaites et que l'autre côté n'a pas appelé ICommunicationObject.Abort sur le canal avant d'appeler Close.Successful in this case means that all delivery guarantees the binding specified were met, and the other side did not call ICommunicationObject.Abort on the channel before calling Close.

La section suivante fournit un exemple de cette approche cliente.The following section provides an example of this client approach.

Gestion des exceptionsHandling Exceptions

La gestion des exceptions dans les applications clientes est simple.Handling exceptions in client applications is straightforward. Si un canal est ouvert, utilisé et fermé à l'intérieur d'un bloc try, cela signifie que la conversation a réussi, à moins qu'une exception ne soit levée.If a channel is opened, used, and closed inside a try block, then the conversation has succeeded, unless an exception is thrown. En général, si une exception est levée, la conversation est abandonnée.Typically, if an exception is thrown the conversation is aborted.

Notes

L’utilisation de l' using instruction ( Using dans Visual Basic) n’est pas recommandée.Use of the using statement (Using in Visual Basic) is not recommended. Cela est dû au fait que la fin de l'instruction using peut provoquer des exceptions qui peuvent masquer d'autres exceptions dont vous devez avoir connaissance.This is because the end of the using statement can cause exceptions that can mask other exceptions you may need to know about. Pour plus d’informations, consultez utiliser Close et Abort pour libérer des ressources clientes WCF.For more information, see Use Close and Abort to release WCF client resources.

L'exemple de code suivant illustre le modèle client recommandé à l'aide d'un bloc try/catch, et non de l'instruction using.The following code example shows the recommended client pattern using a try/catch block and not the using statement.

using System;
using System.ServiceModel;
using System.ServiceModel.Channels;
using Microsoft.WCF.Documentation;

public class Client
{
  public static void Main()
  {
    // Picks up configuration from the config file.
    SampleServiceClient wcfClient = new SampleServiceClient();
    try
    {
      // Making calls.
      Console.WriteLine("Enter the greeting to send: ");
      string greeting = Console.ReadLine();
      Console.WriteLine("The service responded: " + wcfClient.SampleMethod(greeting));

      Console.WriteLine("Press ENTER to exit:");
      Console.ReadLine();

      // Done with service.
      wcfClient.Close();
      Console.WriteLine("Done!");
    }
    catch (TimeoutException timeProblem)
    {
      Console.WriteLine("The service operation timed out. " + timeProblem.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException<GreetingFault> greetingFault)
    {
      Console.WriteLine(greetingFault.Detail.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (FaultException unknownFault)
    {
      Console.WriteLine("An unknown exception was received. " + unknownFault.Message);
      Console.ReadLine();
      wcfClient.Abort();
    }
    catch (CommunicationException commProblem)
    {
      Console.WriteLine("There was a communication problem. " + commProblem.Message + commProblem.StackTrace);
      Console.ReadLine();
      wcfClient.Abort();
    }
  }
}

Imports System.ServiceModel
Imports System.ServiceModel.Channels
Imports Microsoft.WCF.Documentation

Public Class Client
    Public Shared Sub Main()
        ' Picks up configuration from the config file.
        Dim wcfClient As New SampleServiceClient()
        Try
            ' Making calls.
            Console.WriteLine("Enter the greeting to send: ")
            Dim greeting As String = Console.ReadLine()
            Console.WriteLine("The service responded: " & wcfClient.SampleMethod(greeting))

            Console.WriteLine("Press ENTER to exit:")
            Console.ReadLine()

            ' Done with service. 
            wcfClient.Close()
            Console.WriteLine("Done!")
        Catch timeProblem As TimeoutException
            Console.WriteLine("The service operation timed out. " & timeProblem.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch greetingFault As FaultException(Of GreetingFault)
            Console.WriteLine(greetingFault.Detail.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch unknownFault As FaultException
            Console.WriteLine("An unknown exception was received. " & unknownFault.Message)
            Console.ReadLine()
            wcfClient.Abort()
        Catch commProblem As CommunicationException
            Console.WriteLine("There was a communication problem. " & commProblem.Message + commProblem.StackTrace)
            Console.ReadLine()
            wcfClient.Abort()
        End Try
    End Sub
End Class

Notes

La vérification de la valeur de la propriété ICommunicationObject.State est une condition de concurrence et n'est pas recommandée pour déterminer s'il faut réutiliser ou fermer un canal.Checking the value of the ICommunicationObject.State property is a race condition and is not recommended to determine whether to reuse or close a channel.

Les canaux de datagramme ne subissent jamais de défaillance, même si des exceptions se produisent lorsqu'ils sont fermés.Datagram channels never fault even if exceptions occur when they are closed. De plus, les clients non-duplex qui ne parviennent pas à s'authentifier à l'aide d'une conversation sécurisée lèvent en général une exception System.ServiceModel.Security.MessageSecurityException.In addition, non-duplex clients that fail to authenticate using a secure conversation typically throw a System.ServiceModel.Security.MessageSecurityException. Toutefois, si le client duplex qui utilise une conversation sécurisée ne parvient pas à s'authentifier, il reçoit une exception System.TimeoutException.However if the duplex client using a secure conversation fails to authenticate, the client receives a System.TimeoutException instead.

Pour obtenir des informations plus complètes sur l’utilisation des informations d’erreur au niveau de l’application, consultez spécification et gestion des erreurs dans les contrats et les services.For more complete information about working with error information at the application level, see Specifying and Handling Faults in Contracts and Services. Exceptions attendues décrit les exceptions attendues et montre comment les gérer.Expected Exceptions describes expected exceptions and shows how to handle them. Pour plus d’informations sur la gestion des erreurs lors du développement de canaux, consultez gestion des exceptions et des erreurs.For more information about how to handle errors when developing channels, see Handling Exceptions and Faults.

Blocage de client et performancesClient Blocking and Performance

Lorsqu'une application appelle une opération demande-réponse de façon synchrone, le client se bloque jusqu'à ce qu'une valeur de retour soit reçue ou qu'une exception (par exemple System.TimeoutException) soit levée.When an application synchronously calls a request-reply operation, the client blocks until a return value is received or an exception (such as a System.TimeoutException) is thrown. Ce comportement est semblable au comportement local.This behavior is similar to local behavior. Quand une application appelle de façon synchrone une opération sur un canal ou un objet client WCF, le client ne retourne pas de valeur tant que la couche de canal ne peut pas écrire les données sur le réseau ou qu’une exception ne soit levée.When an application synchronously invokes an operation on a WCF client object or channel, the client does not return until the channel layer can write the data to the network or until an exception is thrown. Et bien que le modèle d’échange de messages unidirectionnel (spécifié en marquant une opération avec OperationContractAttribute.IsOneWay défini à true) puisse améliorer la capacité de réponse de certains clients, les opérations unidirectionnelles peuvent également subir un blocage, en fonction de la liaison et des messages qui ont déjà été envoyés.And while the one-way message exchange pattern (specified by marking an operation with OperationContractAttribute.IsOneWay set to true) can make some clients more responsive, one-way operations can also block, depending upon the binding and what messages have already been sent. Les opérations unidirectionnelles concernent uniquement l'échange de messages, ni plus ni moins.One-way operations are only about the message exchange, no more and no less. Pour plus d’informations, consultez services unidirectionnels.For more information, see One-Way Services.

Les grands segments de données peuvent ralentir le traitement client, quel que soit le modèle d’échange de messages.Large data chunks can slow client processing no matter what the message exchange pattern. Pour comprendre comment gérer ces problèmes, consultez données volumineuses et diffusion en continu.To understand how to handle these issues, see Large Data and Streaming.

Si votre application doit effectuer davantage de travail pendant l’exécution d’une opération, vous devez créer une paire de méthodes asynchrones sur l’interface de contrat de service implémentée par votre client WCF.If your application must do more work while an operation completes, you should create an asynchronous method pair on the service contract interface that your WCF client implements. Le moyen le plus simple consiste à utiliser le /async commutateur de l' outil ServiceModel Metadata Utility Tool (Svcutil. exe).The easiest way to do this is to use the /async switch on the ServiceModel Metadata Utility Tool (Svcutil.exe). Pour obtenir un exemple, consultez Comment : appeler des opérations de service de façon asynchrone.For an example, see How to: Call Service Operations Asynchronously.

Pour plus d’informations sur l’amélioration des performances des clients, consultez applications clientes de niveau intermédiaire.For more information about increasing client performance, see Middle-Tier Client Applications.

Autoriser l'utilisateur à sélectionner des informations d'identification de manière dynamiqueEnabling the User to Select Credentials Dynamically

L'interface IInteractiveChannelInitializer permet aux applications d'afficher une interface utilisateur qui permet à l'utilisateur de choisir des informations d'identification avec lesquelles un canal est créé avant le démarrage des minuteries de délai d'attente.The IInteractiveChannelInitializer interface enables applications to display a user interface that enables the user to choose credentials with which a channel is created before the timeout timers start.

Les développeurs d'applications peuvent utiliser un IInteractiveChannelInitializer inséré de deux façons.Application developers can make use of an inserted IInteractiveChannelInitializer in two ways. L’application cliente peut appeler ClientBase<TChannel>.DisplayInitializationUI ou IClientChannel.DisplayInitializationUI (ou une version asynchrone) avant d’ouvrir le canal (approche explicite ) ou appeler la première opération (approche implicite ).The client application can call either ClientBase<TChannel>.DisplayInitializationUI or IClientChannel.DisplayInitializationUI (or an asynchronous version) prior to opening the channel (the explicit approach) or call the first operation (the implicit approach).

Lors de l’utilisation de l’approche implicite, l’application doit appeler la première opération sur une extension ClientBase<TChannel> ou IClientChannel.If using the implicit approach, the application must call the first operation on a ClientBase<TChannel> or IClientChannel extension. Si elle appelle une autre opération que la première, une exception est levée.If it calls anything other than the first operation, an exception is thrown.

Lors de l'utilisation de l'approche explicite, l'application doit exécuter les étapes suivantes, dans l'ordre :If using the explicit approach, the application must perform the following steps in order:

  1. Appelez ClientBase<TChannel>.DisplayInitializationUI ou IClientChannel.DisplayInitializationUI (ou une version asynchrone).Call either ClientBase<TChannel>.DisplayInitializationUI or IClientChannel.DisplayInitializationUI (or an asynchronous version).

  2. Lorsque les initialiseurs ont retourné, appelez la méthode Open sur l'objet IClientChannel ou sur l'objet IClientChannel retourné par la propriété ClientBase<TChannel>.InnerChannel.When the initializers have returned, call either the Open method on the IClientChannel object or on the IClientChannel object returned from the ClientBase<TChannel>.InnerChannel property.

  3. Appelez les opérations.Call operations.

Il est recommandé que les applications de qualité de production contrôlent le processus d'interface utilisateur en adoptant l'approche explicite.It is recommended that production-quality applications control the user-interface process by adopting the explicit approach.

Les applications qui utilisent l'approche implicite appellent les initialiseurs d'interface utilisateur, mais si l'utilisateur de l'application ne répond pas avant la fin du délai d'attente d'envoi de la liaison, une exception est levée lorsque l'interface utilisateur retourne.Applications that use the implicit approach invoke the user-interface initializers, but if the user of the application fails to respond within the send timeout period of the binding, an exception is thrown when the user interface returns.

Voir aussiSee also