Vue d'ensemble d'un client WCF
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 :
Obtenez le contrat de service, les informations de liaison et 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 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 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 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 à 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 Guide pratique : Créer un client. 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 dans 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, 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 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 cliente WCF.
Création d'un nouvel objet WCF
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.
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.
[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<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 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), car elle peut masquer des exceptions dans certains modes d'échec. Pour plus d’informations, consultez les sections suivantes, ainsi que Utilisation de fermer et d’abandonner pour libérer les ressources clientes WCF.
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 les points de terminaison, voir Points de terminaison : Adresses, liaisons et contrats). En règle générale, ces informations se trouvent dans l'élément <point de terminaison> d'un fichier de configuration d'application client, 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="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 en savoir plus sur l'utilisation de plusieurs points de terminaison cibles, consultez les constructeurs ClientBase<TChannel> ou constructeurs 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, 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 WCF et Utiliser fermer et abandonner pour libérer des ressources clientES 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
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<TDetail> où le paramètre de type représente 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 un exemple complet illustrant comment gérer des erreurs dans un client, consultez Exceptions attendues.
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 , 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 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 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.
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 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>
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 Guide pratique pour appeler des opérations de service de façon asynchrone.
Appels des services à l'aide des canaux clients WCF
Les types clients WCF étendent ClientBase<TChannel> 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<TChannel>. Pour plus d’informations, consultez Architecture cliente WCF.