Partager via

Création d'un proxy de service Web XML

  • Article

Par définition, il est possible de communiquer avec les services Web XML sur un réseau en faisant appel aux protocoles industriels standard, notamment SOAP. C'est-à-dire qu'un client et un service Web XML communiquent à l'aide de messages SOAP qui encapsulent les paramètres en entrée et out au format XML. Heureusement, pour les clients de service Web XML, la classe proxy gère la tâche de mappage des paramètres aux éléments XML puis d'envoi du message SOAP sur le réseau.

À condition qu'une description de service existe, une classe proxy peut être générée si la description est conforme au langage WSDL (Web Services Description Language). Une description de service définit comment communiquer avec un service Web XML. Avec une description de service, une classe proxy peut être créée à l'aide de l'outil Wsdl.exe. À son tour, un client de service Web XML peut alors appeler les méthodes de la classe proxy qui communiquent avec un service Web XML sur le réseau en traitant les messages SOAP à destination et en provenance du service. Comme la classe proxy communique avec le service Web XML par le biais d'Internet, il est conseillé de vérifier que sa propriété Url fait référence à une destination de confiance.

Par défaut, la classe proxy utilise SOAP sur HTTP pour communiquer avec le service Web XML. Cependant, Wsdl.exe peut générer des classes proxy pour communiquer avec un service Web XML, à l'aide des protocoles HTTP-GET ou 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 cela est décrit dans le tableau ci-dessous.

Pour générer une classe proxy de service Web XML

  • À l'invite de commande, utilisez Wsdl.exe pour créer une classe proxy, spécifiant (au moins) l'URL vers un service Web XML ou une description de service ou le chemin d'accès à 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 précédemment sont les arguments couramment utilisés pour l'outil Wsdl.exe. Pour la syntaxe complète de l'outil Wsdl.exe, consultez ** Outil Web Services Description Language Tool (Wsdl.exe).

    Paramètre Valeur
    <url or path> URL ou chemin d'accès vers une description de service (fichier décrivant un service Web XML en langage WSDL).

    Si vous spécifiez un fichier, fournissez-en un contenant la description de service. Par exemple :

    mywebservice.wsdl

    Si vous spécifiez une URL, elle doit référencer une page .asmx ou retourner une description de service. Pour les services Web XML créés à l'aide d'ASP.NET, vous pouvez retourner une description de service en ajoutant ?WSDL à l'URL du service. Par exemple,

    https://www.contoso.com/MyWebService.asmx?WSDL
    /language:language Langage dans lequel la classe proxy est générée. Les options disponibles sont CS, VB et JS, qui se réfèrent respectivement à C#, Visual Basic .NET et JScript .NET. Le langage par défaut est C#. (Optionnel)
    /protocol:protocol Protocole utilisé pour communiquer avec les méthodes de service Web XML. Les options disponibles sont SOAP, HTTP-GET et HTTP-POST. Le protocole par défaut est SOAP. (Optionnel)
    /namespace:myNameSpace Espace de noms du proxy généré. La valeur par défaut correspond à l'espace de noms global. (Optionnel)
    /out:filename Nom du fichier à créer contenant la classe proxy. Le nom par défaut repose sur le nom de la classe implémentant le service Web XML. (Optionnel)
    /username:username Nom d'utilisateur à utiliser lors d'une connexion à un serveur Web qui requiert une authentification. (Optionnel)
    /password:password Mot de passe à utiliser lors d'une connexion à un serveur Web qui requiert une authentification. (Optionnel)
    /domain:domain Domaine à utiliser lors d'une connexion à un serveur Web qui requiert une authentification. (Optionnel)

Détails relatifs à la classe proxy générée

Lorsque Wsdl.exe est utilisé pour générer une classe proxy, un seul fichier source est généré dans le langage spécifié. Ce fichier contient une classe proxy exposant les méthodes synchrones et asynchrones pour chaque méthode du service Web XML. Par exemple, si un service Web XML contient une méthode nommée Add, la classe proxy a les méthodes suivantes pour appeler la méthode du service Add : Add, BeginAdd ** et EndAdd. La méthode Add de la classe proxy est utilisée pour communiquer avec la méthode du service Add de manière synchrone, mais les méthodes BeginAdd et EndAdd sont utilisées pour communiquer avec une méthode de service Web XML de manière asynchrone. Pour plus d'informations sur la communication avec les méthodes de service Web XML de manière asynchrone, consultez Communication asynchrone 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 XML. Si une erreur survient pendant la communication, une exception est levée. Pour plus d'informations sur la gestion des exceptions, consultez Gestion et levée d'exceptions dans les services Web XML.

L'ordre des paramètres peut varier par rapport à l'ordre défini dans la méthode de service Web XML et la méthode associée de la classe proxy. Dans la plupart des cas, l'ordre des paramètres correspondra. Cependant, si le service Web XML attend des messages SOAP au format Document, il existe un cas où l'ordre des paramètres ne correspondra pas. Si les paramètres out d'une méthode de service Web XML sont définis avant un paramètre en entrée, ils sont placés après tous les paramètres en entrée dans la classe proxy. Par exemple, dans l'exemple de code suivant, le paramètre out outStr de la méthode de service Web XML MyWebMethod est déclaré avant le paramètre en entrée inStr. Dans la classe proxy néanmoins, le paramètre inStr est déclaré avant outStr.

Dans certains cas, la classe proxy générée par WSDL.exe utilise une approche du dénominateur le moins commun pour effectuer un cast des objets vers un type spécifié dans une description de service. Par conséquent, le type généré dans la classe proxy peut ne pas correspondre aux souhaits ou aux attentes du développeur. 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 casts de type d'objet corrects, ouvrez le fichier contenant la classe proxy générée et remplacez les types d'objet incorrects par le type d'objet attendu.

' Declare MyWebMethod in the XML 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)
[C#]
// Declare MyWebMethod in the XML 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 une approche du dénominateur le moins commun pour effectuer un cast des objets vers un type spécifié dans une description de service. Par conséquent, le type généré dans la classe proxy peut ne pas correspondre aux souhaits ou aux attentes du développeur. 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 casts de type d'objet corrects, ouvrez le fichier contenant la classe proxy générée et remplacez les types d'objet incorrects par le type d'objet attendu.

Avertissements levés par Wsdl.exe

Lorsque vous fournissez plusieurs descriptions de service à Wsdl.exe, les deux messages d'erreur suivants peuvent être déclenchés :

  • Avertissement : Doublon de description de service avec TargetNamespace=<espace de noms du schéma> de l'emplacement <URI du schéma> ignoré.

    Indique au TargetNamespace que deux ou plusieurs des descriptions de service fournies sont identiques. Étant donné que TargetNamespace est supposé être un identificateur unique pour un document XML particulier, qui est dans le cas présent une description de service, Wsdl.exe suppose que les deux descriptions de service sont identiques. Ainsi, Wsdl.exe crée une seule classe proxy pour l'une des descriptions de service. Si ce n'est pas le résultat que vous attendiez, vous pouvez modifier cela. Pour les descriptions de service représentant des services Web XML créés à l'aide d'ASP.NET, vous pouvez appliquer un attribut WebService spécifiant une propriété Namespace unique à la classe implémentant le service Web XML. Cette propriété Namespace est alors utilisée comme TargetNamespace, dans la description de service, pour identifier de manière unique le service Web XML. Pour plus d'informations sur la définition de la propriété Namespace, consultez Application de l'attribut WebService.

  • Avertissement : Doublon de schéma avec TargetNamespace=<espace de noms du schéma> de l'emplacement <URI du schéma> ignoré.

    Indique au TargetNamespace que deux ou plusieurs schémas XML dans les descriptions de service fournies sont identiques. Puisque TargetNamespace est supposé être un identificateur unique pour un document XML particulier, le schéma XML dans le cas présent, Wsdl.exe suppose que les deux schémas XML sont identiques. Ainsi, Wsdl.exe crée une classe pour un seul des schémas. Si ce n'est pas le résultat attendu, le TargetNamespace pour chaque schéma XML doit être remplacé par un identificateur URI unique. La modification exacte de TargetNamespace dépend de l'origine des schémas XML particuliers.

Voir aussi

Création de clients de service Web XML | Découverte des services Web XML | Création de clients pour les services Web XML | Exploration des services Web XML existants créés à l'aide d'ASP.NET | Communication asynchrone avec les services Web XML | Accès à des services Web XML à partir d'un navigateur