Procédure pas à pas : utilisation d'enveloppes XML (de base)

Cet exemple illustre le désassemblage de base d'enveloppes XML par l'implémentation en partie d'un système de suivi des erreurs fictif. Cet exemple remplit les conditions suivantes :

1. les messages d'erreur sont consignés dans divers sites physiques de l'entreprise, puis envoyés vers un emplacement central pour être traités par différents systèmes principaux ;

2. Les messages d'erreur sont écrits au format XML.

3. Un message d'erreur peut être envoyé seul sans enveloppe ou en tant que lot contenu dans une enveloppe.

Prérequis

Pour cet exemple, vous devez être à l’aise avec la création de projets BizTalk, la signature d’un assembly et l’utilisation de la console d’administration BizTalk Server pour afficher les applications et les ports. Vous devez également être à l’aise avec les idées présentées dans Procédure pas à pas : déploiement d’une application BizTalk de base.

Ce que fait cet exemple

Cet exemple traite les messages entrants contenant soit un seul message d'erreur, soit un lot de messages d'erreur par la définition d'un schéma d'enveloppe et l'utilisation du pipeline XmlDisassembler.

Exemple

Pour créer l'exemple, suivez les étapes présentées dans les sections ci-après.

Créer un projet BizTalk

Avant de concevoir une solution, vous devez créer un projet BizTalk, vous assurer qu'il porte un nom fort, puis lui attribuer un nom d'application. Attribuer un nom d'application empêche BizTalk Server de déployer la solution dans l'application BizTalk par défaut.

Pour créer et configurer un projet BizTalk

1. Utilisez Visual Studio pour créer un projet BizTalk. Appelez le projet BasicXMLEnvelope.

2. Générez un fichier de clé et attribuez-le au projet. Pour plus d’informations sur cette tâche, consultez Configuration d’un fichier de clé d’assembly de nom fort.

3. Dans les propriétés de configuration de déploiement du projet, attribuez un nom d’application et définissez Redémarrer les instances d’hôte sur True. La définition de cet indicateur indique à l'hôte d'effacer toutes les instances mises en cache de l'assembly.

Créer le schéma d’erreur

Cette étape permet de créer le schéma d'erreur. Il définit le message clé du système.

Pour créer le schéma d'erreur

1. Ajoutez un nouveau schéma intitulé « Error » au projet.

2. Remplacez l’espace de noms cible pour le schéma par http://BasicXMLEnvelope.

3. Remplacez la propriété de schéma, élément FormDefault , sous la catégorie Avancé , par Qualifié. Vous indiquez ainsi que les éléments déclarés localement doivent être qualifiés par l'espace de noms cible dans un document d'instance.

4. Renommez le nœud racine « Error » et créez cinq éléments enfants avec les types indiqués :

   • ID, xs:int

   • Type, xs:int

   • Priority, xs:string

   • Description, xs:string

   • ErrorDateTime, xs:string

     Votre schéma doit présenter l'aspect suivant :

     

5. Créez un exemple de message pour ce schéma. Vous pouvez ainsi vérifier que les messages seuls hors enveloppe sont correctement traités. Voici un exemple de message :

   <Error xmlns="http://BasicXMLEnvelope">  
     <ID>1</ID>  
     <Type>5</Type>  
     <Priority>Low</Priority>  
     <Description>Sprocket widget prints reports slowly.</Description>  
     <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
   </Error>  
   

   Enregistrez ce message dans un fichier du répertoire du projet.

Création du schéma d'enveloppe

L'enveloppe contient un ou plusieurs messages d'erreur. Dans cet exemple simple, l'enveloppe ne dispose pas de ses propres propriétés et éléments.

Pour créer le schéma d'enveloppe

1. Ajoutez un nouveau schéma intitulé « Envelope » au projet BasicXMLEnvelope.

2. Remplacez l’espace de noms cible par http://BasicXMLEnvelope.

3. Modifiez le nom du nœud racine de « Root » en « Envelope ».

4. Marquez le schéma en tant que schéma d'enveloppe. Cliquez sur le <nœud Schéma> . Dans le volet Propriétés, définissez la propriété de référence de schéma Enveloppe sur OK.

5. Définissez la propriété Body XPath . Pour ce faire, cliquez sur le nœud Enveloppe . Dans le Fenêtre Propriétés, cliquez sur le bouton de sélection (...) dans la propriété Body XPath, sélectionnez Enveloppe, puis cliquez sur OK.

6. Ajoutez tout élément enfant au nœud Envelope. Le message d'erreur sera contenu dans cet élément. Votre schéma doit présenter l'aspect suivant :

   

7. Créez un exemple de message contenant une enveloppe et un ou plusieurs exemples de message. Voici un exemple de message :

   <Envelope xmlns="http://BasicXMLEnvelope">  
     <Error>  
       <ID>102</ID>  
       <Type>0</Type>  
       <Priority>High</Priority>  
       <Description>Sprocket query fails.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
     <Error>  
       <ID>16502</ID>  
       <Type>2</Type>  
       <Priority>Low</Priority>  
       <Description>Time threshold exceeded.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
   </Envelope>  
   

   Enregistrez ce message dans un fichier du répertoire du projet.

Déploiement et configuration des ports de réception et d'envoi

Une fois les schémas créés, vous devez compiler et déployer le projet. Lorsque le projet est déployé, vous pouvez utiliser la console Administration de BizTalk Server pour configurer les ports d'envoi et de réception.

Pour déployer BasicXMLEnvelope

1. Dans Visual Studio, choisissez Déployer BasicXMLEnvelope dans le menu Générer. Il sera généré et déployé sur BizTalk Server en tant qu'application « BasicXMLEnvelope ».

2. Dans la console Administration BizTalk Server, développez le groupe Applications pour vérifier que BasicXMLEnvelope est présent en tant qu’application personnalisée.

Pour configurer le port de réception

1. Utilisez Windows Explorer pour créer un répertoire nommé « Receive » sous le répertoire du projet BasicXMLEnvelope.

2. Dans la console Administration BizTalk Server, développez l’application BasicXMLEnvelope, cliquez avec le bouton droit sur Ports de réception, pointez sur Nouveau, puis cliquez sur Port de réception unidirectionnel.

3. Dans la boîte de dialogue Propriétés du port de réception , définissez le nom du port sur « Receive ».

4. Cliquez avec le bouton droit sur Emplacements de réception, puis cliquez sur Nouveau pour ajouter un port de réception. Nommez le nouveau port « ReceiveError ». Définissez le pipeline de réception sur XMLReceive. Pour Type de transport, sélectionnez FICHIER, puis cliquez sur Configurer.

5. Sélectionnez le répertoire de réception créé ci-dessus, puis cliquez sur OK. Votre port de réception devrait à présent être configuré. Cliquez sur OK pour fermer.

Pour configurer le port d'envoi

1. Utilisez Windows Explorer pour créer un répertoire nommé « Send » sous le répertoire du projet BasicXMLEnvelope.

2. Dans la console Administration BizTalk Server, développez l’application BasicXMLEnvelope, cliquez avec le bouton droit sur Envoyer les ports, pointez sur Nouveau, puis cliquez sur Unidirectionnel statique.

3. Dans la boîte de dialogue Propriétés du port d’envoi, définissez le nom du port sur « Send ».

4. Pour Type de transport, sélectionnez FICHIER, puis cliquez sur Configurer. Définissez le dossier de destination sur le répertoire d’envoi que vous avez créé précédemment, puis cliquez sur OK.

5. Cliquez sur Filtres et ajoutez un filtre unique :

   • BTS. MessageType == http://BasicXMLEnvelope#Error

6. Cliquez sur OK pour terminer la configuration du port d’envoi. Votre port d'envoi devrait à présent être configuré.

Exécution de l'exemple

Il est maintenant temps d'exécuter l'exemple. Après avoir utilisé la console Administration de BizTalk Server pour lancer l'application BasicXMLEnvelope, copiez les fichiers de test dans l'emplacement de réception et observez le résultat produit dans l'emplacement d'envoi.

Pour exécuter l'exemple BasicXMLEnvelope

1. Dans la console Administration BizTalk Server, cliquez avec le bouton droit sur l’application BasicXMLEnvelope, puis cliquez sur Démarrer. Ceci inscrit et démarre les ports d'envoi et de réception

2. Faites glisser le fichier exemple dans le répertoire de réception. Si vous utilisez les exemples fournis plus haut, vous devez trouver trois messages d'erreur distincts dans l'emplacement d'envoi lorsque le traitement est terminé.

Extension de l’exemple

Vous pouvez étendre l'exemple afin qu'il réponde à d'autres exigences. Cette section traite deux scénarios communs :

• Si un lot d'erreurs est envoyé dans une enveloppe, les échecs de messages individuels dans le désassemblage ne doivent pas empêcher le traitement des messages qui ne rencontrent pas d'échec.

• Les erreurs doivent être remises à différents emplacements en fonction de leur priorité. Les messages dont la priorité est élevée sont expédiés tandis que les autres priorités sont traités via les canaux normaux.

  Les sections suivantes étendent l'exemple pour gérer ces cas.

Traitement des échanges récupérables

BizTalk Server prend en charge le traitement d’échange récupérable. Grâce à cette fonction, vous pouvez vous assurer que les lots de messages échouent de manière individuelle dans le désassemblage, et non en tant que lot.

Pour configurer l'exemple pour le traitement des échanges récupérables

1. Dans la console Administration BizTalk Server, développez l’application BasicXMLEnvelope, cliquez sur Ports de réception, puis double-cliquez sur le port de réception. Il s'agit du port que vous avez précédemment créé.

2. Dans la boîte de dialogue Propriétés du port de réception, cliquez sur Emplacements de réception. Cliquez sur Propriétés pour afficher la boîte de dialogue Propriétés de l’emplacement de réception ReceiveError . Cliquez sur le bouton de points de suspension (...) pour le pipeline de réception.

3. Dans la boîte de dialogue Configurer le pipeline - XMLReceive , définissez la propriété Recoverable Interchange Processing sur True, puis cliquez sur OK.

4. Cliquez sur OK pour fermer la boîte de dialogue Propriétés de l’emplacement de réception, puis cliquez sur OK pour fermer la boîte de dialogue Propriétés du port de réception.

Pour créer un fichier exemple et exécuter l'exemple

1. Pour créer un fichier exemple, faites une copie du fichier d'enveloppe créé dans l'exemple, ajoutez un espace de noms inexistant à l'une des instances Error, puis enregistrez le fichier :

   <Envelope xmlns="http://BasicXMLEnvelope">  
     <Error>  
       <ID>102</ID>  
       <Type>0</Type>  
       <Priority>High</Priority>  
       <Description>Sprocket query fails to return any sprockets even though some exist</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
     <Error xmlns="http://ThisIsAnError">  
       <ID>16502</ID>  
       <Type>2</Type>  
       <Priority>Low</Priority>  
       <Description>Time threshold exceeded.</Description>  
       <ErrorDateTime>1999-05-31T13:20:00.000-05:00</ErrorDateTime>  
     </Error>  
   </Envelope>  
   

2. Dans la console Administration BizTalk Server, cliquez sur Applications et vérifiez que l’application BasicXMLEnvelope est en cours d’exécution.

3. Déposez le message dans l'emplacement de réception. Après traitement, vous devez trouver le premier message dans l'emplacement d'envoi et le second, avec une priorité basse, dans la file d'attente des messages interrompus.

Routage basé sur le contenu

Vous avez la possibilité d'utiliser le routage basé sur le contenu pour acheminer les messages en fonction de leur contenu. Dans ce scénario, l'acheminement est basé sur la priorité : les messages dont la priorité est élevée sont dirigés vers un emplacement d'envoi, et ceux dont la priorité est moyenne ou basse le sont vers un emplacement d'envoi différent.

Pour étendre l'exemple, vous devez effectuer les tâches suivantes :

1. Promouvez le champ Priorité dans le schéma d’erreur dans le projet BasicXMLEnvelope. Le routage basé sur le contenu s'appuie sur les propriétés promues pour acheminer les messages. Pour plus d’informations, consultez Promotion des propriétés.

2. Créer et configurer deux ports d'envoi supplémentaires. Les ports utilisent un filtre pour s'assurer qu'ils reçoivent les messages appropriés.

Pour promouvoir le champ Priorité du schéma Error

1. Avec le projet BasicXMLEnvelope ouvert dans Visual Studio, ouvrez le schéma d’erreur et développez le nœud Erreur .

2. Cliquez avec le bouton droit sur l’élément Priority , pointez sur Promouvoir, puis cliquez sur Promotion rapide.

3. Cliquez sur OK pour confirmer l’ajout d’un nouveau schéma de propriété pour les propriétés promues.

4. Dans Visual Studio, dans Explorateur de solutions, ouvrez le nouveau schéma de propriétés PropertySchema.xsd. Supprimez « Field1 » du schéma.

5. Recompilez et redéployez la solution. Dans le menu Générer, sélectionnez Déployer BasicXMLEnvelope.

6. Le projet était configuré pour réinitialiser l'instance hôte une fois la solution redéployée. Si vous avez modifié cet élément, vous devez arrêter et démarrer l'hôte.

Pour configurer le port d'envoi de priorité basse et moyenne

1. Utilisez Windows Explorer pour créer un répertoire nommé « SendLowMediumPriority » sous le répertoire du projet BasicXMLEnvelope.

2. Dans la console Administration BizTalk Server, développez l’application BasicXMLEnvelope, cliquez avec le bouton droit sur Envoyer les ports, pointez sur Nouveau, puis cliquez sur Unidirectionnel statique.

3. Dans la boîte de dialogue Propriétés du port d’envoi, définissez le nom du port sur « SendLowMediumPriority ».

4. Pour Type de transport, sélectionnez FICHIER, puis cliquez sur Configurer. Définissez le dossier de destination sur le répertoire que vous avez créé auparavant. Cliquez sur OK pour fermer.

5. Cliquez sur Filtres et ajoutez trois expressions de filtre :

   • BTS. MessageType == http://BasicXMLEnvelope#Error et

   • BasicXMLEnvelope.PropertySchema.Priority == Low Or

   • BasicXMLEnvelope.PropertySchema.Priority == Medium

6. Cliquez sur OK pour terminer la configuration du port d’envoi de faible et moyenne priorité.

Pour configurer le port d'envoi de priorité élevée

1. Utilisez Windows Explorer pour créer un répertoire nommé « SendHighPriority » sous le répertoire du projet BasicXMLEnvelope.

2. Dans la console Administration BizTalk Server, développez l’application BasicXMLEnvelope, cliquez avec le bouton droit sur Envoyer les ports, pointez sur Nouveau, puis cliquez sur Unidirectionnel statique.

3. Dans la boîte de dialogue Propriétés du port d’envoi, définissez le nom du port sur « SendHighPriority ».

4. Pour Type de transport, sélectionnez FICHIER, puis cliquez sur Configurer. Définissez le dossier de destination sur le répertoire que vous avez créé auparavant. Cliquez sur OK pour fermer.

5. Cliquez sur Filtres et ajoutez deux expressions de filtre :

   • BTS. MessageType == http://BasicXMLEnvelope#Error et

   • BasicXMLEnvelope.PropertySchema.Priority == High

6. Cliquez sur OK pour terminer la configuration du port d’envoi à priorité élevée.

Pour tester la solution de routage

1. Dans la console Administration BizTalk Server, développez le groupe Applications, cliquez avec le bouton droit sur l’application BasicXMLEnvelope, puis cliquez sur Démarrer. Lorsque vous êtes invité à confirmer, cliquez sur Démarrer. Les nouveaux ports d'envoi sont ainsi inscrits.

2. Déposez le message test dans l'emplacement de réception. Notez la façon dont les messages d'erreur sont acheminés vers les différents emplacements :

   • Les messages dont la priorité est basse, moyenne ou élevée et dont le traitement n'échoue pas sont acheminés vers l'emplacement d'envoi d'origine (configuré au cœur de l'exemple) et l'emplacement d'envoi par priorité. Pour les messages dont la priorité est basse ou moyenne, une copie s'affiche à la fois dans l'emplacement d'envoi d'origine et dans l'emplacement d'envoi de priorité basse ou moyenne.

   • Si le traitement des échanges récupérables est activé, le message d'erreur ayant échoué n'est pas acheminé et le message n'ayant pas échoué est acheminé comme prévu. Le message ayant échoué n'est pas acheminé car son type ne correspond pas au type utilisé dans les filtres configurés.

Voir aussi

Traitement des échanges récupérables
Promotion des propriétés
CBRSample (exemple BizTalk Server)