Copyright © 2001-2007 Nicholas Quaine.
Home   Bases   Côté-Serveur   Côté-Client   Démos   FAQ   Ressources
Côté-Client
1. Vue générale
2. Apache SOAP
3. SOAP::Lite
4. MS SOAP
Packages
Les versions à utiliser
Sun Java
Apache SOAP
Active Perl
SOAP::Lite
MS SOAP Toolkit

Précédent   1    2    3    4    Suivant
SOAP Côté Client
4. Toolkit Microsoft SOAP

Cette section vous montre comment écrire un client en utilisant le Toolkit Microsoft SOAP. Le Toolkit MS SOAP est un ensemble de DLLs qui peuvent être exploités par n'importe quel langage compris dans la famille des COM (Component Object Model) (tant que, bien sûr, l' exécutable s'exécute sur un système Win32). Le langage que nous verrons dans ce tutorial est Visual Basic.

Introduction
Nous allons écrire un client VB SOAP extrêmement simple qui va exploiter le Service de Citations comme décrit et développé dans la Section 4 de SOAP Côté Serveur.

Le code VB lié à SOAP dans le client que nous allons développer peut facilement être incorporé dans une Macro VB pour permettre à un tableur Excel de communiquer en SOAP. Nous allons aussi regarder comment le faire. Bien qu'il est vrai qu'on peut exploiter les DLLs du Toolkit MS SOAP à partir d'autres langages que VB, il n'est pas dans notre intention de tous les couvrir.

Comme c'est toujours le cas quand vous écrivez des clients pour n'importe quel service SOAP, assurez vous à l'avance que vous êtes familier du service et des signatures de ses méthodes.

Nous allons construire un seul client VB qui va exploiter les trois méthodes du service.

Notez qu'il y a en fait deux API dans le toolkit Microsoft SOAP. Elles sont d'une partl'API dite de haut-niveau (qui implique l'utilisation de fichiers wsdl et wsml pour la description des services), et d'autre part, l'API dite de bas-niveau (qui ne demande pas la préparation de tels fichiers, ce qui rend le résultat plus dense en terme de code mais en même temps plus puissant). L'API utilisée dans ce tutorial est l'API de bas-niveau.

Vérifiez votre Version de Visual Basic
Vous allez avoir besoin de Visual Basic 6.0 Service Pack 4 ou plus (c'est la version livrée avec Visual Studio 6.0 Service Pack 4). Pour vérifier votre version, ouvrez Visual Basic et sélectionnez Aide / A propos de Microsoft Visual Basic.

Si vous avez Visual Basic 6.0 mais un Service Pack plus ancien vous pouvez télécharger le SP4 à partir de Microsoft Product Support Services.

Si vous avez une version antérieure à 6.0, ou n'avez pas Visual Basic du tout, malheureusement, contrairement au reste des packages utilisés dans ce site, vous ne pouvez pas le télécharger gratuitement. Vous pouvez par contre regarder le code source et exécuter la démo VB trouvée dans la Section de Démo.

Installer le Toolkit MS SOAP
Avant que vous n'installiez ce toolkit, assurez que vous avez sur votre système les composants suivants:

  • Internet Explorer 5.5 ou plus (vous serez assuré d'avoir les versions correctes des bibliothèques de HTTP Connector) - Si vous avez une version antérieure, vous pouvez télécharger gratuitement à partir de la page de téléchargement IE du site Microsoft.
  • Assurez vous que vous avez la fonctionnalité Microsoft Installer (MSI, qui vous permet d'exécuter le programme d'installation du toolkit SOAP) - elle est standard pour Windows 2000 et Me donc les utilisateurs de ces systèmes n'ont pas besoin de faire quoi que ce soit. Si vous utilisez Windows NT, alors télécharger MSI 1.1+ pour NT. Si vous utilisez Win95 ou Win98 alors télécharger MSI 1.1+ pour Win9x.

Maintenant pour le Toolkit lui-même. Nous allons utiliser le Toolkit Microsoft SOAP 2.0 SP2. Pour l'installer sur votre machine, allez dans la zone de téléchargement MS SOAP Toolkit et sélectionnez le téléchargement nommé "Soap Toolkit 2.0 SP2", lisez et acceptez la licence (si vous êtes d'accord avec les termes de celle-ci) et sauvegardez le fichier sur votre machine. Vous devriez maintenant avoir un fichier appelé soaptoolkit20.exe. Il s'agit d'un exécutable self-extracting (à extraction automatique) qui exploite les fonctionnalités MSI. Lancez le et suivez les instructions à l'écran pour installer le toolkit. Quand demandé, optez pour l'installation COMPLETE.

Comprendre l'API
Ce qui suit est l'essentiel du code VB nécessaire pour exploiter l'API. C'est une paraphrase du code source VB téléchargeable plus bas dans cette page. Notez que nous avons juste extrait le code en relation avec SOAP, donc ce que vous voyez quand vous ouvrez les sources téléchargeables est en gros la même chose mais légèrement réarrangée et plus prolixe pour traiter les aspects GUI du client (que nous n'expliquerons pas car ils sont triviaux). Suivez les étapes suivantes pour invoquer un service via l'API:

  • Définissez des constantes qui seront utilisées pour construire l'enveloppe SOAP (si vous voulez en savoir plus sur ces URLs, voyez la section sur les Messages SOAP) ainsi que les données d'identification de votre service (URL du Serveur SOAP, URI du Service et nom de la méthode du service).
  •   Private Const ENC = "http://schemas.xmlsoap.org/soap/encoding/"
      Private Const XSI = "http://www.w3.org/1999/XMLSchema-instance"
      Private Const XSD = "http://www.w3.org/1999/XMLSchema"
      URL = "http://localhost:8080/soap/servlet/rpcrouter"
      URI = "urn:QuotationService"
      Method = "getQuotationsByAuthor"
    
  • Instanciez vos Connector, Serializer et Reader SOAP. Le Connector va gérer la connexion HTTP, le Serializer vous aidera à construire l' enveloppe SOAP et le Reader vous aidera à accéder au résultat.
  •   Dim Connector As SoapConnector
      Dim Serializer As SoapSerializer
      Dim Reader As SoapReader
      Set Connector = New HttpConnector
      Set Serializer = New SoapSerializer
      Set Reader = New SoapReader
    
  • Préparez le Connector à entrer en communication avec le Serveur SOAP. Notez que la donnée "SoapAction" n'a aucune conséquence du côté serveur, et que donc son contenu peut être n'importe quoi - c'est néanmoins une bonne idée de lui donner les valeurs de l'URI et du nom de la méthode pour faciliter l'identification quand vous déboguer et lisez les messages SOAP.
  •   Connector.Property("EndPointURL") = URL
      Call Connector.Connect
      Connector.Property("SoapAction") = URI & "#" & Method
      Call Connector.BeginMessage
    
  • Associez votre Serializer avec votre Connector.
  •   Serializer.Init Connector.InputStream
    
  • Commencez l'Enveloppe SOAP et spécifiez le schéma d'encodage XML.
  •   Serializer.startEnvelope , ENC
      Serializer.SoapNamespace "xsi", XSI
      Serializer.SoapNamespace "SOAP-ENC", ENC
      Serializer.SoapNamespace "xsd", XSD
    
  • Commencez le corps du message - l'élément racine est toujours le Service URI et la méthode.
  •   Serializer.startBody
      Serializer.startElement Method, URI, , "method"
    
  • Rédigez chaque paramètre de méthode comme un fils de l'élément racine.
  •   Serializer.startElement "Author"
      Serializer.SoapAttribute "type", , "xsd:string", "xsi"
      Serializer.writeString "Wilde, Oscar"
      Serializer.endElement
    
  • Terminez l'élément racine, le corps et l'enveloppe.
  •   Serializer.endElement
      Serializer.endBody
      Serializer.endEnvelope
    
  • Terminer le message entraîne son envoi.
  •   Connector.EndMessage
    
  • Charger le résultat dans le Reader.
  •   Reader.Load Connector.OutputStream
    
  • Si aucune erreur n'apparaît au chargement du Reader, vous pouvez alors continuer et récupérer dans le DOM (Document Object Model) contenu dans le Reader le résultat de l'invocation. Il y a beaucoup de façons de faire, allant des méthodes hautement spécialisées dans la tâche à réaliser (et ainsi très efficaces) aux méthodes plus générales et réutilisables qui ne sont pas aussi efficaces (comme la méthode que vous verrez dans les sources téléchargeables).
  •   If Not Reader.Fault Is Nothing Then
        MsgBox Reader.faultstring.text, vbExclamation
      Else
        Set Result = Reader.DOM
        //analyser le DOM pour extraire l'ensemble du résultat
      End If

Ecrire le Client
Tout d'abord, télécharger le fichier zip contenant le code source (les feuilles VB (forms)) pour le client du Service de Citations écrit en Visual Basic. Extrayez le contenu entier du zip dans le répertoire de votre choix. Ouvrez ensuite Visual Basic et créez un nouveau projet (de type Standard EXE), enlever la feuille par défaut et ajouter au projet les TROIS feuilles téléchargées. Assurez vous de déclarer la feuille principale (main form) comme étant l'objet de démarrage (startup object) (utilisez: Projet Propriétés / Onglet Général (Project Properties / General tab)). Avant d'exécuter, vous devez ajouter les références vers les DLLs du Toolkit MS SOAP. Ceci fait, elles devraient ressembler à (les quatre dernières références étant celles à ajouter):
client-4 diagram-1

Exécuter le Client
Vous pouvez soit compiler le projet en exécutable et le lancer ou l'exécuter à partir de Visual Basic. L'interface est assez simple et n'exige aucune explication. Une fois de plus, le code tel quel présume que vous avez le Service de Citation tournant sur votre machine (sur localhost:8080). Si ce n'est pas le cas, alors vous pouvez exécuter les clients avec notre serveur de démonstration SOAP. Pour cela, remplacez simplement localhost:8080 par services.xmethods.net dans l'espace fourni pour l'URL. Pour plus d'information sur notre serveur de démonstration, référez vous à la Section de Démo.

Incorporer dans Microsoft Excel
Il est relativement facile d'incorporer dans Microsoft Excel le code que nous venons d'écrire en tant que Macro VB. Téléchargez et ouvrez ce tableur Excel [note: cliquer droit sur ce lien et sauvegarder le fichier sur votre disque dur] pour avoir une idée de la façon dont c'est fait (notez que, si c'est demandé par Excel, vous allez devoir activer les macros pour une exécution correcte). Jetez un oeil au code qui se cache derrière le bouton "Get All Quotations". Notez que tout ce que nous avons vraiment fait est de prendre le code de l'exemple VB ci-dessus et de le modifier pour lire l'entrée et écrire la sortie dans la feuille Excel plutôt que dans la feuille VB. Seule la méthode getAllQuotations est implémentée dans cette feuille de calcul. Nous laissons comme exercice au lecteur l'implémentation des autres méthodes. Pour ceux qui ne sont habitués à l'interface des macros VB, vous devrez ajouter la barre d'outils "boite à outils des contrôles" ("Control Toolbox") (voir Outils/Personnaliser/Barre d'outils ou Tools/Customize/Toolbars), ensuite activer le mode création (Design Mode) en cliquant le bouton à l'équerre bleue. Vous allez alors pouvoir cliquer droit le bouton "Get All Quotations" dans la feuille de calcul et voir le code correspondant. Notez que les quatre mêmes DLLS du Toolkit SOAP ont été ajouté comme références projet (dans l'éditeur de Macro VB voyez Outils/References (Tools/References)). Une fois de plus, le code tel quel présume que vous avez le Service de Citation tournant sur votre machine (sur localhost:8080). Si ce n'est pas le cas, alors vous pouvez exécuter les clients avec notre serveur de démonstration SOAP. Pour cela, remplacez simplement localhost:8080 par services.xmethods.net dans l'espace fourni pour l'URL.

[ Nicholas Quaine ]

Home

Copyright © 2001-2007 Nicholas Quaine. Tout droit reservé.