Création d'un proxy de service Web XML

Article
02/27/2011

Cette rubrique est spécifique à une technologie existante. Les services Web XML et les clients du service Web XML doivent à présent être créés à l'aide de Windows Communication Foundation.

Par définition, il est possible de communiquer avec les services Web via un réseau à l'aide de protocoles conformes aux normes de l'industrie, notamment SOAP. Autrement dit, un client et un service Web communiquent à l'aide de messages SOAP qui encapsulent les paramètres d'entrée et de sortie en XML. Heureusement, pour les clients de service Web, la classe proxy s'occupe du mappage des paramètres en éléments XML, puis de l'envoi du message SOAP via le réseau.

Tant qu'une description de service existe, une classe proxy peut être générée si la description de service est conforme au Web Services Description Language (WSDL). Une description de service définit comment communiquer avec un service Web. Avec une description de service, une classe proxy peut être créée avec l'outil Wsdl.exe. Ensuite, un client de service Web peut appeler des méthodes de la classe proxy, qui communiquent avec un service Web via le réseau en traitant les messages SOAP envoyés à destination et en provenance du service Web. Étant donné que la classe proxy communique avec le service Web par Internet, il est recommandé de vérifier que la propriété Url de la classe proxy fait référence à une destination approuvée.

Par défaut, la classe proxy utilise SOAP via HTTP pour communiquer avec le service Web. Toutefois, Wsdl.exe peut générer des classes proxy pour communiquer avec un service Web à l'aide du protocole HTTP-GET ou du protocole HTTP-POST. Pour spécifier que la classe proxy doit utiliser HTTP-GET ou HTTP-POST, fournissez le commutateur /protocol à l'outil Wsdl.exe, comme décrit dans le tableau suivant.

Utilisation de Wsdl.exe pour générer une classe proxy de service Web XML

Vous pouvez utiliser l'outil Web Services Description Language (Wsdl.exe) à partir d'une invite de commandes pour créer une classe proxy, en spécifiant (au minimum) l'URL d'un service Web ou d'une description de service, ou le chemin d'accès d'une description de service enregistrée.

Wsdl /language:language /protocol:protocol /namespace:myNameSpace /out:filename /username:username /password:password /domain:domain <url or path>

Remarque :
Les arguments répertoriés ici sont les arguments communément utilisés pour Wsdl.exe. Pour la syntaxe complète de Wsdl.exe, consultez l'outil Web Services Description Language (Wsdl.exe).

Paramètre	Valeur
<url ou path>	URL ou chemin d'accès d'une description de service (fichier décrivant un service Web dans WSDL). Si vous spécifiez un fichier, fournissez un fichier contenant la description de service. Par exemple : mywebservice.wsdl Si vous spécifiez une URL, l'URL doit faire référence à une page .asmx ou retourner une description de service. Pour les services Web créés à l'aide d'ASP.NET, vous pouvez retourner une description de service en ajoutant ?WSDL à l'URL du service Web. Par exemple : https://www.contoso.com/MyWebService.asmx?WSDL.
/language:langage	Langage dans lequel la classe proxy est générée. Les options disponibles incluent CS, VB et JS, faisant respectivement référence à C#, Visual Basic .NET et JScript .NET. Le langage par défaut est C#. (facultatif)
/protocol:protocol	Protocole utilisé pour communiquer avec les méthodes de service Web. Les options disponibles incluent SOAP, HTTP-GET et HTTP-POST. Le protocole par défaut est SOAP. (facultatif)
/namespace:myNameSpace	Espace de noms du proxy généré. La valeur par défaut correspond à l'espace de noms global. (Facultatif)
/out:nomfichier	Nom du fichier à créer contenant la classe proxy. Le nom par défaut est basé sur le nom de la classe qui implémente le service Web. (Facultatif)
/username:nomutilisateur	Nom d'utilisateur à utiliser lors d'une connexion à un serveur Web exigeant une authentification. (facultatif)
/password:password	Mot de passe à utiliser lors d'une connexion à un serveur Web requérant une authentification. (facultatif)
/domain:domain	Domaine à utiliser lors d'une connexion à un serveur Web requérant une authentification. (facultatif)

Détails de la classe proxy générée

Lorsque Wsdl.exe est utilisé pour générer une classe proxy, un fichier source unique est généré dans le langage spécifié. Ce fichier contient une classe proxy qui expose à la fois des méthodes synchrones et asynchrones pour chaque méthode de service Web du service Web. Par exemple, si un service Web contient une méthode de service Web nommée Add, la classe proxy dispose des méthodes suivantes pour appeler la méthode de service Web Add : Add, BeginAdd, et EndAdd. La méthode Add de la classe proxy est utilisée pour communiquer de façon synchrone avec la méthode de service Web Add, mais les méthodes BeginAdd et EndAdd sont utilisées pour communiquer de façon asynchrone avec une méthode de service Web. Pour plus d'informations sur le sujet suivant la communication asynchrone avec les méthodes de service Web, consultez Communications asynchrones avec les services Web XML.

Chaque méthode de la classe proxy générée contient le code approprié pour communiquer avec la méthode de service Web. Si une erreur se produit pendant la communication avec le service Web et la classe proxy, une exception est levée. Pour plus d'informations sur le sujet suivant la gestion des exceptions, consultez Gestion et levée d'exceptions dans les services Web XML.

L'ordre des paramètres peut différer entre l'ordre défini dans la méthode de service Web et la méthode associée de la classe proxy. Dans la plupart des cas, l'ordre des paramètres correspond. Toutefois, si le service Web attend des messages SOAP mis en forme dans le style Document, il y a un cas où l'ordre des paramètres ne correspond pas. Si une méthode de service Web a des paramètres de sortie définis avant un paramètre d'entrée, les paramètres de sortie sont placés après tous les paramètres d'entrée dans la classe proxy. Par exemple, dans l'exemple de code suivant, la méthode de service Web MyWebMethod a le paramètre de sortie outStr déclaré avant le paramètre d'entrée inStr. Toutefois, dans la classe proxy, le paramètre inStr est déclaré avant outStr.

' Declare MyWebMethod in the Web service.
MyWebMethod(ByRef outStr As String, inStr As String)

' This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(inStr As String, ByRef outStr As String)

// Declare MyWebMethod in the Web service.
MyWebMethod(out string outStr, string inStr)

// This is the corresponding MyWebMethod in the proxy class.
MyWebMethod(string inStr, out string outStr).

Dans certains cas, la classe proxy générée par Wsdl.exe utilise l'approche du plus petit dénominateur commun pour la conversion d'objets en un type spécifié dans une description de service. Par conséquent, le type généré dans la classe proxy peut ne pas être ce que le développeur souhaite ou attend. Par exemple, lorsque Wsdl.exe rencontre un type ArrayList dans une description de service, il crée un tableau Object dans la classe proxy générée. Pour garantir des conversions de type d'objet correctes, ouvrez le fichier contenant la classe proxy générée et remplacez les types d'objets incorrects par le type d'objet attendu.

Avertissements levés par Wsdl.exe

Lors de la fourniture de plusieurs descriptions de service à Wsdl.exe, les deux messages d'erreur suivants peuvent être déclenchés :

Avertissement : description de service dupliquée avec TargetNamespace=<espace de noms du schéma> dans <URI du schéma> ignorée.

Indique le TargetNamespace pour deux descriptions de service identiques fournies ou plus. Comme le TargetNamespace est censé être un identificateur unique pour un document XML particulier, qui dans ce cas est une description de service, Wsdl.exe suppose que les deux descriptions de service sont identiques. Ce faisant, Wsdl.exe génère seulement une classe proxy pour l'une des descriptions de service. Si ce n'est pas le résultat que vous souhaitiez, vous pouvez le modifier. Pour les descriptions de service représentant des services Web créés à l'aide d'ASP.NET, vous pouvez appliquer un attribut WebService qui spécifie une propriété Namespace unique à la classe implémentant le service Web. Cette propriété Namespace est ensuite utilisée comme TargetNamespace dans la description de service pour identifier le service Web de façon unique.
Avertissement : schéma dupliqué avec TargetNamespace=<espace de noms du schéma> dans <URI du schéma> ignoré.

Indique le TargetNamespace pour deux schémas XML identiques ou plus dans les descriptions de service fournies. Le TargetNamespace étant censé être un identificateur unique pour un document XML particulier, qui dans ce cas est le schéma XML, Wsdl.exe suppose que les deux schémas XML sont identiques. Ce faisant, Wsdl.exe génère une classe pour un seul schéma. Si ce n'est pas le résultat attendu, le TargetNamespace pour chaque schéma XML doit être changé en URI unique. La façon dont le TargetNamespace est modifié dépend de l'origine des schémas XML particuliers.

Voir aussi

Partager via

Création d'un proxy de service Web XML

Utilisation de Wsdl.exe pour générer une classe proxy de service Web XML

Détails de la classe proxy générée

Avertissements levés par Wsdl.exe

Voir aussi

Tâches

Concepts

Autres ressources

Ressources supplémentaires