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

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.