Vue d'ensemble d'un client WCFWCF Client Overview

Cette section décrit les applications clientes, comment configurer, créer et utiliser un client Windows Communication Foundation (WCF) et comment sécuriser les applications clientes.This section describes what client applications do, how to configure, create, and use a Windows Communication Foundation (WCF) client, and how to secure client applications.

Utilisation des objets clients WCFUsing WCF Client Objects

Une application cliente est une application managée qui utilise un client WCF pour communiquer avec une autre application.A client application is a managed application that uses a WCF client to communicate with another application. Pour créer une application cliente pour un service WCF, vous devez effectuer les étapes suivantes:To create a client application for a WCF service requires the following steps:

  1. Obtenez le contrat de service, les informations de liaison et d'adresse pour un point de terminaison de service.Obtain the service contract, bindings, and address information for a service endpoint.

  2. Créez un client WCF à l’aide de ces informations.Create a WCF client using that information.

  3. Appelez les opérations.Call operations.

  4. Fermez l’objet client WCF.Close the WCF client object.

Les sections suivantes traitent de ces étapes et fournissent de brèves introductions aux problèmes suivants :The following sections discuss these steps and provide brief introductions to the following issues:

  • Gestion des erreurs.Handling errors.

  • Configuration et sécurisation des clients.Configuring and securing clients.

  • Création d'objets de rappel pour les services duplex.Creating callback objects for duplex services.

  • Appels des services de façon asynchrone.Calling services asynchronously.

  • Appels des services à l'aide de canaux clients.Calling services using client channels.

Obtenir le contrat de service, les liaisons et les adressesObtain the Service Contract, Bindings, and Addresses

Dans WCF, les services et les clients modélisent des contrats à l’aide d’attributs, d’interfaces et de méthodes managés.In WCF, services and clients model contracts using managed attributes, interfaces, and methods. Pour se connecter à un service dans une application cliente, vous devez obtenir les informations de type pour le contrat de service.To connect to a service in a client application, you need to obtain the type information for the service contract. En règle générale, vous utilisez l' outil ServiceModel Metadata Utility Tool (Svcutil. exe), qui télécharge les métadonnées à partir du service, les convertit en fichier de code source géré 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.Typically, you do this by using the ServiceModel Metadata Utility Tool (Svcutil.exe), which downloads metadata from the service, converts it to a managed source code file in the language of your choice, and creates a client application configuration file that you can use to configure your WCF client object. Par exemple, si vous envisagez de créer un objet client WCF pour appeler MyCalculatorServiceun, et que vous savez que les métadonnées de ce service http://computerName/MyCalculatorService/Service.svc?wsdlsont publiées à l’adresse, l’exemple de code suivant montre comment utiliser Svcutil. ClientCode.vb exe pour obtenir un fichier qui contient le contrat de service en code managé.For example, if you are going to create an WCF client object to invoke a MyCalculatorService, and you know that the metadata for that service is published at http://computerName/MyCalculatorService/Service.svc?wsdl, then the following code example shows how to use Svcutil.exe to obtain a ClientCode.vb file that contains the service contract in managed code.

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.You can either compile this contract code into the client application or into another assembly that the client application can then use to create an WCF client object. Vous pouvez utiliser le fichier de configuration pour configurer l'objet client pour se connecter correctement au service.You can use the configuration file to configure the client object to properly connect to the service .

Pour obtenir un exemple de ce processus, consultez Procédure: Créez un client.For an example of this process, see How to: Create a Client. Pour obtenir des informations plus complètes sur les contrats, consultez contrats.For more complete information about contracts, see Contracts.

Créer un objet client WCFCreate a WCF Client Object

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.A WCF client is a local object that represents a WCF service in a form that the client can use to communicate with the remote service. 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 l’objet client directement pour appeler les opérations de service.WCF client types implement the target service contract, so when you create one and configure it, you can then use the client object directly to invoke service operations. 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 out ref paramètres.The WCF run time converts the method calls into messages, sends them to the service, listens for the reply, and returns those values to the WCF client object as return values or out or ref parameters.

Vous pouvez également utiliser des objets de canal client WCF pour vous connecter avec des services et les utiliser.You can also use WCF client channel objects to connect with and use services. Pour plus d’informations, consultez architecture du client WCF.For details, see WCF Client Architecture.

Création d'un nouvel objet WCFCreating a New WCF Object

Pour illustrer l'utilisation d'une classe ClientBase<TChannel>, supposons que le contrat de service simple suivant a été généré depuis une application de service.To illustrate the use of a ClientBase<TChannel> class, assume the following simple service contract has been generated from a service application.

Notes

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.If you are using Visual Studio to create your WCF client, objects are loaded automatically into the object browser when you add a service reference to your project.

[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 ClientBase<TChannel> qui étend et l’interface ISampleServicede contrat de service.If you are not using Visual Studio, examine the generated contract code to find the type that extends ClientBase<TChannel> and the service contract interface ISampleService. Dans ce cas, ce type ressemble au code suivant :In this case, that type looks like the following code:

[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.This class can be created as a local object using one of the constructors, configured, and then used to connect to a service of the type ISampleService.

Nous vous recommandons 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.It is recommended that you create your WCF client object first, and then use it and close it inside a single try/catch block. Vous ne devez pas utiliser using l’instructionUsing (dans Visual Basic), car elle peut masquer des exceptions dans certains modes d’échec.You should not use the using statement (Using in Visual Basic) because it may mask exceptions in certain failure modes. Pour plus d’informations, consultez les sections suivantes, ainsi que l' utilisation de Close et Abort pour libérer des ressources clientes WCF.For more information, see the following sections as well as Use Close and Abort to release WCF client resources.

Contrats, liaisons et adressesContracts, Bindings, and Addresses

Avant de pouvoir créer un objet client WCF, vous devez configurer l’objet client.Before you can create a WCF client object, you must configure the client object. Plus précisément, il doit avoir un point de terminaison de service à utiliser.Specifically, it must have a service endpoint to use. Un point de terminaison est la combinaison d’un contrat de service, d’une liaison et d’une adresse.An endpoint is the combination of a service contract, a binding, and an address. (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 > 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.(For more information about endpoints, see Endpoints: Addresses, Bindings, and Contracts.) Typically, this information is located in the <endpoint> element in a client application configuration file, such as the one the Svcutil.exe tool generates, and is loaded automatically when you create your client object. Les deux types de clients WCF ont également des surcharges qui vous permettent de spécifier ces informations par programme.Both WCF client types also have overloads that enable you to programmatically specify this information.

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.For example, a generated configuration file for an ISampleService used in the preceding examples contains the following endpoint information.

<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>.This configuration file specifies a target endpoint in the <client> element. Pour plus d’informations sur l’utilisation de plusieurs points de terminaison ClientBase<TChannel>.ClientBase<TChannel> cibles, ChannelFactory<TChannel>.ChannelFactory<TChannel> consultez les constructeurs ou.For more information about using multiple target endpoints, see the ClientBase<TChannel>.ClientBase<TChannel> or the ChannelFactory<TChannel>.ChannelFactory<TChannel> constructors.

Opérations appelantesCalling Operations

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.Once you have a client object created and configured, create a try/catch block, call operations in the same way that you would if the object were local, and close the WCF client object. 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é.When the client application calls the first operation, WCF automatically opens the underlying channel, and the underlying channel is closed when the object is recycled. (Vous pouvez également ouvrir et fermer explicitement le canal avant ou après l'appel des autres opérations.)(Alternatively, you can also explicitly open and close the channel prior to or subsequent to calling other operations.)

Par exemple, si vous avez le contrat de service suivant :For example, if you have the following service contract:

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 le montre l’exemple de code suivant.You can call operations by creating a WCF client object and calling its methods, as the following code example demonstrates. Notez que l’ouverture, l’appel et la fermeture de l’objet client WCF se produisent dans un bloc try/catch unique.Note that the opening, calling, and closing of the WCF client object occurs within a single try/catch block. Pour plus d’informations, consultez accès aux services à l’aide d’un client WCF et utilisation de Close et Abort pour libérer des ressources clientes WCF.For more information, see Accessing Services Using a WCF Client and Use Close and Abort to release WCF client resources.

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

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.Exceptions can occur in a client application when opening the underlying client channel (whether explicitly or automatically by calling an operation), using the client or channel object to call operations, or when closing the underlying client channel. 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.It is recommended at a minimum that applications expect to handle possible System.TimeoutException and System.ServiceModel.CommunicationException exceptions in addition to any System.ServiceModel.FaultException objects thrown as a result of SOAP faults returned by operations. 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<TDetail> où le paramètre de type représente le type de détail de l’erreur SOAP.SOAP faults specified in the operation contract are raised to client applications as a System.ServiceModel.FaultException<TDetail> where the type parameter is the detail type of the SOAP fault. Pour plus d’informations sur la gestion des conditions d’erreur dans une application cliente, consultez envoi et réception d’erreurs.For more information about handling error conditions in a client application, see Sending and Receiving Faults. Pour obtenir un exemple complet, montre comment gérer les erreurs dans un client, consultez exceptions attendues.For a complete sample the shows how to handle errors in a client, see Expected Exceptions.

Configuration et sécurisation des clientsConfiguring and Securing 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.Configuring a client starts with the required loading of target endpoint information for the client or channel object, usually from a configuration file, although you can also load this information programmatically using the client constructors and properties. Toutefois, des étapes de configuration supplémentaires sont nécessaires pour activer certain comportement client et pour de nombreux scénarios de sécurité.However, additional configuration steps are required to enable certain client behavior and for many security scenarios.

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.For example, security requirements for service contracts are declared in the service contract interface, and if Svcutil.exe created a configuration file, that file usually contains a binding that is capable of supporting the security requirements of the service. Dans certains cas, toutefois, davantage de configuration de sécurité peut être requis, tel que configurer des informations d'identification du client.In some cases, however, more security configuration may be required, such as configuring client credentials. Pour obtenir des informations complètes sur la configuration de la sécurité pour les clients WCF, consultez Sécurisation des clients.For complete information about the configuration of security for WCF clients, see Securing Clients.

De plus, certaines modifications personnalisées peuvent être activées dans des applications clientes, telles que les comportements d'exécution personnalisés.In addition, some custom modifications can be enabled in client applications, such as custom run-time behaviors. Pour plus d’informations sur la configuration d’un comportement client personnalisé, consultez Configuration des comportements des clients.For more information about how to configure a custom client behavior, see Configuring Client Behaviors.

Création d'objets de rappel pour les services duplexCreating Callback Objects for Duplex Services

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.Duplex services specify a callback contract that the client application must implement in order to provide a callback object for the service to call according to the requirements of the contract. 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.Although callback objects are not full services (for example, you cannot initiate a channel with a callback object), for the purposes of implementation and configuration they can be thought of as a kind of service.

Les clients de services duplex doivent :Clients of duplex services must:

  • Implémenter une classe de contrat de rappel.Implement a callback contract class.

  • Créez une instance de la classe d’implémentation de contrat de rappel et utilisez- System.ServiceModel.InstanceContext la pour créer l’objet que vous transmettez au constructeur client WCF.Create an instance of the callback contract implementation class and use it to create the System.ServiceModel.InstanceContext object that you pass to the WCF client constructor.

  • Appeler des opérations et traiter des rappels d'opération.Invoke operations and handle operation callbacks.

Les objets clients WCF duplex fonctionnent comme leurs équivalents non duplex, sauf qu’ils exposent les fonctionnalités nécessaires pour prendre en charge les rappels, y compris la configuration du service de rappel.Duplex WCF client objects function like their nonduplex counterparts, with the exception that they expose the functionality necessary to support callbacks, including the configuration of the callback service.

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.For example, you can control various aspects of callback object runtime behavior by using properties of the System.ServiceModel.CallbackBehaviorAttribute attribute on the callback class. 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.Another example is the use of the System.ServiceModel.Description.CallbackDebugBehavior class to enable the return of exception information to services that call the callback object. Pour plus d’informations, consultez services duplex.For more information, see Duplex Services. Pour obtenir un exemple complet, consultez duplex.For a complete sample, see 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.On Windows XP computers running Internet Information Services (IIS) 5.1, duplex clients must specify a client base address using the System.ServiceModel.WSDualHttpBinding class or an exception is thrown. L'exemple de code suivant montre comment procéder.The following code example shows how to do this in 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 effectuer cette opération dans un fichier de configurationThe following code shows how to do this in a configuration file

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

Appels des services de façon asynchrone.Calling Services Asynchronously

Le mode d'appel des opérations dépend entièrement du développeur du client.How operations are called is entirely up to the client developer. 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é.This is because the messages that make up an operation can be mapped to either synchronous or asynchronous methods when expressed in managed code. 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.Therefore, if you want to build a client that calls operations asynchronously, you can use Svcutil.exe to generate asynchronous client code using the /async option. Pour plus d’informations, consultez Guide pratique pour Appeler des opérations de servicede façon asynchrone.For more information, see How to: Call Service Operations Asynchronously.

Appels des services à l'aide des canaux clients WCFCalling Services Using WCF Client Channels

Les types de clients ClientBase<TChannel>WCF étendent lui-même System.ServiceModel.IClientChannel à partir de l’interface pour exposer le système de canal sous-jacent.WCF client types extend ClientBase<TChannel>, which itself derives from System.ServiceModel.IClientChannel interface to expose the underlying channel system. Vous pouvez appeler des services à l'aide du contrat de service cible avec la classe System.ServiceModel.ChannelFactory<TChannel>.You can invoke services by using the target service contract with the System.ServiceModel.ChannelFactory<TChannel> class. Pour plus d’informations, consultez architecture du client WCF.For details, see WCF Client Architecture.

Voir aussiSee also