Modification de messages SOAP à l'aide d'extensions SOAP

  • Article

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.

Les extensions SOAP permettent aux développeurs d'augmenter les fonctionnalités d'un service Web en modifiant les messages SOAP envoyés vers et depuis un service Web ou un client de service Web. Par exemple, vous pouvez implémenter un algorithme de chiffrement ou de compression pour qu'il s'exécute avec un service Web existant.

Pour comprendre le fonctionnement d'une extension SOAP, il est utile de comprendre d'abord la durée de vie d'un service Web. Pour plus d'informations, consultez Anatomie de la durée de vie d'un service Web XML.

L'illustration suivante souligne les phases majeures de l'appel d'un client à un service Web.

Durée de vie d'un service Web XML

Comme vous pouvez le voir, le .NET Framework sérialise et désérialise du XML par phases à la fois sur l'ordinateur du service Web et l'ordinateur client du service Web. Une extension SOAP peut être injectée dans l'infrastructure pour inspecter ou modifier les messages SOAP avant et après chacune de ces phases de sérialisation et de désérialisation. Par exemple, une extension SOAP de chiffrement peut chiffrer la partie XML du message SOAP après que le .NET Framework a sérialisé les arguments du client, puis déchiffrer le message SOAP sur le serveur Web avant que le .NET Framework ne désérialise le message SOAP. Ces phases où une extension SOAP peut inspecter ou modifier le message SOAP sont définies dans l'énumération SoapMessageStage. Dans ce cas, l'extension SOAP chiffre à l'étape AfterSerialize et déchiffre à l'étape BeforeDeserialize.

En général, lorsqu'une extension SOAP modifie le contenu d'un message SOAP, les modifications doivent être faites à la fois sur le client et sur le serveur. C'est-à-dire que si une extension SOAP doit s'exécuter sur le client et chiffrer le message SOAP, une extension SOAP correspondante doit déchiffrer le message SOAP sur le serveur. Si le message SOAP n'est pas déchiffré, l'infrastructure ASP.NET ne peut pas désérialiser le message SOAP dans un objet.

Bien sûr, une extension SOAP qui ne modifie pas le message SOAP, telle qu'une extension SOAP qui enregistre simplement les messages SOAP, peut s'exécuter sur le client ou le serveur uniquement. Dans ce cas, le destinataire reçoit le même message SOAP que si aucune extension SOAP ne s'exécutait et l'infrastructure ASP.NET peut désérialiser le message SOAP. De même, si l'extension SOAP ne modifie pas le SOAP d'une façon qui rende la désérialisation impossible, l'extension SOAP n'a pas besoin de s'exécuter à la fois sur le client et le serveur.

Extension de la classe SOAPExtension

Pour implémenter une extension SOAP, dérivez une classe de la classe SoapExtension. Il y a trois méthodes de la classe SOAPExtension qui doivent être implémentées :

L'implémentation de ces méthodes est expliquée dans la Procédure pas à pas : altération du message SOAP à l'aide d'extensions SOAP.

La méthode ChainStream est passée un objet Stream et retourne un objet Stream. Comme l'extension SOAP s'exécute pendant chaque SoapMessageStage et modifie le message SOAP, une extension SOAP doit lire dans le Stream passé dans ChainStream et écrire dans le Stream retourné de ChainStream. Par conséquent, dans la méthode ChainStream, il est important d'assigner les deux références Stream aux variables membre.

La classe qui dérive de SoapExtension utilise les méthodes GetInitializer et Initialize pour initialiser les données internes, selon le service Web ou la méthode de service Web à laquelle elle s'applique. Par exemple, une extension SOAP qui enregistre le message SOAP envoyée vers et depuis une méthode de service Web peut initialiser le nom d'un fichier pour enregistrer les informations d'enregistrement (selon le nom du service Web ou la méthode de service Web avec lequel l'extension SOAP s'exécute).

Le point auquel l'infrastructure de services Web appelle la méthode GetInitializer et les paramètres passés à la méthode dépendent de la façon dont l'extension SOAP est configurée :

  • Si l'extension SOAP est configurée à l'aide d'un attribut, GetInitializer est appelé par l'infrastructure de services Web lors du premier accès à une method de service Web.

  • Si l'extension SOAP est configurée dans un fichier de configuration, GetInitializer est appelé par l'infrastructure de services Web uniquement lors du premier accès au service Web entier.

L'infrastructure de services Web met en cache l'objet que la méthode GetInitializer retourne. Puis à chaque fois que l'extension SOAP s'exécute avec ce service Web ou cette méthode de service Web, l'infrastructure passe l'objet d'initialiseur à la méthode Initialize.

Le traitement réel étendu au-delà du traitement SOAP standard est exécuté par la méthode ProcessMessage. Chaque fois l'infrastructure de services Web appelle ProcessMessage, elle passe (comme argument) l'instance d'une classe dérivée de SoapMessage qui contient des informations à propos du message SOAP à cette étape particulière. Si l'extension SOAP s'exécute avec un service Web, un objet SoapServerMessage est passé. Si l'extension SOAP s'exécute avec un client de service Web, un objet SoapClientMessage est passé.

Extensions SOAP et exceptions

Les extensions SOAP ne doivent jamais lever elles-mêmes d'exception. Toutefois, elles peuvent ajouter des informations sur les exceptions à la propriété Exception sur l'objet SoapMessage passé dans la méthode ProcessMessage.

Elles peuvent également servir de gestionnaire d'exceptions dans toute une application à l'aide de la même fonctionnalité pour intercepter toutes les exceptions dans l'application pour laquelle l'extension SOAP est installée et exécuter certains comportements, notamment la modification de l'erreur SOAP retournée.

Ordre d'appel des méthodes d'extension SOAP

Maintenant que vous avez regardé les méthodes qu'une extension SOAP remplace, regardez quand l'infrastructure de services Web appelle des méthodes d'extension SOAP dans tout l'appel d'une méthode de service Web. Les étapes suivantes supposent que l'extension SOAP s'exécute à la fois sur le client et le serveur. Si l'extension SOAP ne s'exécute pas à la fois sur le client et le serveur, les étapes associées à l'extension SOAP s'exécutant sur chacun sont ignorées par le .NET Framework.

Le côté client prépare un message de demande

  1. Un client appelle une méthode sur la classe proxy.

  2. Une nouvelle instance de l'extension SOAP est créée sur le client.

  3. Si c'est la première fois que cette extension SOAP s'exécute avec ce service Web sur le client, la méthode GetInitializer est appelée sur l'extension SOAP s'exécutant sur le client.

  4. La méthode Initialize est appelée.

  5. La méthode ChainStream est appelée.

  6. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur BeforeSerialize.

  7. ASP.NET sur l'ordinateur client sérialise les arguments de la méthode de service Web en XML.

  8. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur AfterSerialize.

  9. ASP.NET sur l'ordinateur client envoie le message SOAP via le réseau au serveur Web qui héberge le service Web.

Le côté serveur reçoit un message de demande et prépare une réponse

  1. ASP.NET sur le serveur Web reçoit le message SOAP.

  2. Une nouvelle instance de l'extension SOAP est créée sur le serveur Web.

  3. Sur le serveur Web, si c'est la première fois que cette extension SOAP s'exécute avec ce service Web côté de serveur, la GetInitializer méthode est appelée sur l'extension SOAP s'exécutant sur le serveur.

  4. La méthode Initialize est appelée.

  5. La méthode ChainStream est appelée.

  6. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur BeforeDeserialize.

  7. ASP.NET désérialise les arguments dans le XML.

  8. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur AfterDeserialize.

  9. ASP.NET crée une nouvelle instance de la classe qui implémente le service Web et appelle la méthode de service Web en passant les arguments désérialisés. Cet objet réside sur le même ordinateur que le serveur Web.

  10. La méthode de service Web exécute son code, en définissant finalement la valeur de retour et tous paramètres de sortie.

  11. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur BeforeSerialize.

  12. ASP.NET sur le serveur Web sérialise la valeur de retour et les paramètres de sortie en XML.

  13. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur AfterSerialize.

  14. ASP.NET renvoie le message de réponse SOAP via le réseau au client de service Web.

Le côté client reçoit un message de réponse

  1. ASP.NET sur l'ordinateur client reçoit le message SOAP.

  2. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur BeforeDeserialize.

  3. ASP.NET désérialise le XML dans la valeur de retour et les paramètres de sortie.

  4. La méthode ProcessMessage est appelée avec SoapMessageStage ayant la valeur AfterDeserialize.

  5. ASP.NET passe la valeur de retour et les paramètres de sortie à l'instance de la classe proxy.

  6. Le client reçoit la valeur de retour et les paramètres de sortie.

Implémentation de l'extension SOAP

Il y a deux façons d'exécuter une extension SOAP sur un client ou une application serveur. Premièrement, vous pouvez configurer l'application pour exécuter l'extension. Pour configurer votre extension SOAP pour qu'elle exécute toutes les méthodes Web sur tous les services Web, surtout un vroot, modifiez la section <soapExtensionTypes>, élément dans le fichier Web.config. Le code suivant montre que la valeur d'attribut type doit être sur une ligne et inclure le nom complet qualifié de l'extension, plus la version, la culture et jeton de clé publique de l'assembly signé.

<configuration>
 <system.web>
    <webServices>
      <soapExtensionTypes>
        <add type="Contoso.MySoapExtension, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" 
priority="1" group="0"/>
        </soapExtensionTypes>
    </webServices>
  </system.web>
</configuration>

Deuxièmement, vous pouvez créer un attribut personnalisé qui s'applique à une méthode de service Web. Pour créer l'attribut personnalisé, créez une classe qui dérive de SoapExtensionAttribute. Pour plus d'informations sur la création d'un attribut personnalisé, consultez Comment : implémenter une extension SOAP. Pour plus d'informations sur la création d'attributs personnalisés, consultez Création d'attributs personnalisés.

esw638yk.note(fr-fr,VS.100).gifRemarque :
Lors de l'implémentation d'une extension SOAP, il est possible qu'une attaque par déni de service (DOS, Denial of Service) soit tentée si votre extension utilise un XmlTextReader pour lire le flux de données. Une façon d'empêcher une telle attaque est de garantir que la propriété ProhibitDtd ait la valeur true.

Priorités et groupes de priorité

À l'aide d'attributs ou d'une configuration, une priorité peut être assignée aux extensions SOAP, ce qui permet de déterminer l'ordre relatif d'exécution lorsque plusieurs extensions SOAP sont configurées pour s'exécuter avec une méthode de service Web XML. Plus la priorité d'une extension SOAP est élevée, plus elle s'exécute près du message SOAP envoyé ou reçu sur le réseau. Les extensions SOAP font partie de l'un des trois groupes de priorité. Dans chaque groupe, la propriété priority distingue chaque membre. Plus la propriété priority est basse, plus la priorité relative est élevée (0 étant la valeur la plus élevée).

Les trois groupes de priorité relative pour les extensions SOAP sont : extensions SOAP configurées à l'aide d'un attribut et extensions SOAP spécifiées dans le fichier de configuration avec un paramètre group de 0 ou de 1. Leur priorité est organisée comme suit :

  • Groupe de priorité la plus élevée : extensions SOAP configurées à l'aide d'un fichier de configuration avec un paramètre group de 0.

  • Groupe de priorité moyenne : extensions SOAP configurées à l'aide d'un attribut.

  • Groupe de priorité la moins élevée : extensions SOAP configurées à l'aide d'un fichier de configuration avec un paramètre group de 1.

L'exemple de code suivant est un fichier de configuration qui spécifie que l'extension SOAP Logger.LoggerExtension s'exécute dans le groupe de priorité relative 0 et a une priorité de 1.

<configuration>
 <system.web>
   <webServices>
     <soapExtensionTypes>
      <add type="Logger.LoggerExtension,logger"
           priority="1"
           group="0" />
     </soapExtensionTypes>
    </webServices>
 </system.web>
</configuration>

Voir aussi

Tâches

Comment : implémenter une extension SOAP

Référence

SoapExtension
SoapExtensionAttribute
SoapMessageStage
LogicalMethodInfo

Concepts

Modification de messages SOAP à l'aide d'extensions SOAP
Anatomie de la durée de vie d'un service Web XML
Création de clients de service Web XML

Autres ressources

Configuring Applications
Services Web XML utilisant ASP.NET