MQSCorrelationSetOrchestration (exemple BizTalk Server)

Article
05/04/2023

L'exemple MQSCorrelationSetOrchestration illustre le mode d'utilisation de l'identificateur de corrélation MQSeries pour la corrélation de messages envoyés à une file d'attente MQSeries vers une orchestration en cours d'exécution. L’orchestration définit l’identificateur de corrélation MQSeries et les valeurs d’identificateur de message à l’aide des propriétés MQMD_CorrelId et MQMD_MsgID . Le gestionnaire de file d'attente MQSeries copie la valeur MessageID dans la propriété CorrelationID du message.

Prérequis

Cet exemple suppose que vous avez installé IBM WebSphere MQSeries sur le même serveur que celui que vous exécutez BizTalk Server.

Fonctions de l'exemple

Cet exemple illustre la manière de définir un identificateur de message et un identificateur de corrélation dans un message envoyé à un serveur IBM WebSphere MQSeries Server. Il s'agit d'une méthode que vous pouvez utiliser pour mettre en corrélation un message avec une instance de l'orchestration en cours d'exécution. Lorsque le gestionnaire de file d'attente MQSeries reçoit le message, il copie la valeur MessageID dans la propriété CorrelationID du message. Cet ID de corrélation (MQMD_CorrelId) est ensuite utilisé dans l’orchestration pour associer le message de réponse sur MQSeries au instance utilisé pour envoyer des messages à MQSeries.

Comment cet exemple est conçu et pourquoi

Cet exemple illustre un scénario dans lequel un document en cours de traitement par une orchestration peut être envoyé à une file d'attente MQSeries (probablement en vue d'un traitement supplémentaire) et retourné à l'orchestration en cours d'exécution.

Accès à l'exemple

<Samples Path>\AdaptersUsage\MQSeriesAdapter\MQSCorrelationSetOrchestration

Le tableau suivant présente les fichiers de cet exemple et décrit leur fonction.

File	Description
MQSCorrelationSetOrchestration.btproj, MQSCorrelationSetOrchestration.sln	Fichiers de projet et de solution de l'application.
MQSCorrelationSetOrchestration.odx	Orchestration de l'application.
MQSCorrelationSetOrchestration.snk	Fichier de clé de nom fort.
Setup.bat	Crée et initialise l'exemple.

Comment utiliser cet exemple

Incorporez la logique de cet exemple si vous devez envoyer un message à MQSeries Server dans l'une des étapes du workflow général.

Pour créer la file d'attente MQSeries à l'aide de WebSphere MQ Explorer

Cliquez sur Démarrer, pointez sur Programmes, pointez sur IBM WebSphere MQ, puis cliquez sur WebSphere MQ Explorer.
Double-cliquez sur Gestionnaires de files d’attente, puis double-cliquez sur le gestionnaire de files d’attente par défaut. Le gestionnaire de files d’attente par défaut est généralement nommé QM_<machine_name> où machine_name est le nom de votre ordinateur.
Cliquez avec le bouton droit sur Files d’attente, pointez sur Nouveau, puis cliquez sur File d’attente locale.
Dans la boîte de dialogue Créer une file d’attente locale , dans Nom de la file d’attente, tapez « MQCorrelation », puis cliquez sur OK.

Pour créer l’emplacement de réception et la file d’attente MQSeries

Ouvrez la console Administration BizTalk Server.
Développez BizTalk Server Administration, BizTalk Group, Applications, puis l’application requise.
Cliquez avec le bouton droit sur Ports de réception, pointez sur Nouveau, puis cliquez sur Port de réception unidirectionnel.
Dans la boîte de dialogue Propriétés du port de réception unidirectionnel , dans la zone Nom , tapez « MQIn », puis cliquez sur OK.
Dans le volet gauche, cliquez sur l’onglet Emplacements de réception , puis sur Nouveau.
Dans la boîte de dialogue Propriétés de l’emplacement de réception, dans la zone Nom , tapez « MQIn ».
Dans la zone Type de transport , sélectionnez MQSeries.
Dans la zone Gestionnaire de réception , sélectionnez BizTalkServerApplication.
Dans la zone Pipeline de réception , sélectionnez Microsoft.BizTalk.DefaultPipelines.PassThruReceive.
Cliquez sur Configurer.
Dans la boîte de dialogue Propriétés du transport MQSeries , dans la zone Intervalle d’interrogation , tapez « 10 ».
Dans la zone Définition de la file d’attente , cliquez sur le bouton points de suspension (...) .
Dans la boîte de dialogue Définition de la file d’attente , dans la zone Nom du serveur , tapez le nom de votre ordinateur.
Dans la zone Gestionnaire de files d’attente , sélectionnez le gestionnaire de files d’attente par défaut.
Dans la zone File d’attente , tapez « MQCorrelation », puis cliquez sur Exporter.
Dans la boîte de dialogue Exporter , cliquez sur Créer une file d’attente, puis surOKou Terminé jusqu’à ce que vous ayez quitté toutes les boîtes de dialogue.

Pour créer le port d'envoi vers MQSeries

Cliquez avec le bouton droit sur Ports d’envoi, pointez sur Nouveau, puis cliquez sur Port d’envoi unidirectionnel statique.
Dans la boîte de dialogue Propriétés du port d’envoi, dans la zone Nom , tapez « MQOut ».
Dans la zone Type de transport , sélectionnez MQSeries.
Dans la zone Envoyer le pipeline , sélectionnez Microsoft.BizTalk.DefaultPipelines.PassThruTransmit.
Cliquez sur Configurer.
Dans la boîte de dialogue Propriétés du transport MQSeries , dans la zone Définition de file d’attente , cliquez sur le bouton de sélection (...) .
Dans la boîte de dialogue Définition de la file d’attente , dans la zone Nom du serveur , tapez le nom de votre ordinateur.
Dans la zone Gestionnaire de files d’attente , sélectionnez le gestionnaire de files d’attente par défaut.
Dans la zone File d’attente , tapez « MQCorrelation », puis cliquez sur OK.
Cliquez sur OK jusqu’à ce que vous ayez quitté toutes les boîtes de dialogue.

Activation de l'emplacement de réception et démarrage du port d'envoi

Dans la console Administration BizTalk Server, cliquez sur Ports de réception.
Dans le volet d’informations, cliquez avec le bouton droit sur l’emplacement de réception MQIn , puis cliquez sur Activer.
Dans le volet d’informations, cliquez avec le bouton droit sur le port d’envoi MQOut , puis cliquez sur Démarrer.

Pour créer les dossiers utilisés par l'application

Sur votre lecteur C :\ , créez un dossier nommé « temp » s’il n’existe pas déjà.
Sous le répertoire C :\temp , créez des dossiers nommés « Pickup » et « Dropit ».

Création et déploiement de l'exemple

Dans une fenêtre de commande, accédez au dossier suivant :

<Samples Path>\AdaptersUsage\MQSeriesAdapter\MQSCorrelationSetOrchestration
Exécutez le fichier Setup.bat, qui effectue les actions suivantes :
1. création d'une clé de nom fort pour le projet ;
2. compilation et déploiement du projet d'orchestration.
3. création d'un port d'envoi et d'un port de réception avec l'adaptateur FILE.

Lier et démarrer l'orchestration

Dans la console Administration BizTalk Server, développez le dossier Orchestrations.
Dans le volet d’informations, cliquez avec le bouton droit sur l’orchestration MQSCorrelationSetOrchestration , puis cliquez sur Lier.

Liez les ports d'orchestration aux ports d'envoi et aux emplacements de réception suivants :

Port d'orchestration	Port de messagerie/Emplacement de réception
FileReceivePort	MQSCorrelationSetOrchestration.FileReceivePort
MQSeriesResponseReceivePort	MQIn
MQSeriesRequestSendPort	MQOut
FileSendPort	MQSCorrelationSetOrchestration.FileSendPort

Cliquez sur Hôte.
Dans la zone Hôte , sélectionnez BizTalkServerApplication, puis cliquez sur OK.
Dans Ports d’envoi, cliquez avec le bouton droit sur MQSCorrelationSetOrchestration.FileSendPort, puis sélectionnez Démarrer.
Dans Emplacements de réception, cliquez avec le bouton droit sur MQSCorrelationSetOrchestration.FileReceivePort , puis sélectionnez Activer.
Cliquez avec le bouton droit sur l’orchestration, puis cliquez sur Démarrer.

Notes

Le démarrage de l'orchestration inscrit l'orchestration automatiquement.

Pour tester l'application

Placez un fichier dans le dossier C :\Temp\Pickup .
Examinez le fichier dans le dossier C :\Temp\Dropit .

Notes

Si vous désactivez l’emplacement de réception MQIn, vous pouvez examiner le message dans WebSphere MQ Explorer et voir que les identificateurs de message et de corrélation sont définis. Pour ce faire, lancez le Explorer WebSphere MQ et examinez le message placé dans la file d’attente MQCorrelation. Les identificateurs de message et de corrélation s’affichent sous l’onglet Identificateurs de la boîte de dialogue Propriétés du message .

Notes

Dans un scénario de production, vous souhaiterez probablement affecter un ID unique à chaque message envoyé vers la file d'attente MQSeries. Cela peut se faire en modifiant la forme Expression dans l'orchestration. Modifiez les lignes suivantes afin de définir ces propriétés avec un ID unique de 24 octets :

MQSeriesRequestSendMessageModified(MQSeries.MQMD_MsgId) = "111213141516171819202122232425262728293031323334";

MQSeriesRequestSendMessageModified(MQSeries.MQMD_CorrelId) = "111213141516171819202122232425262728293031323334";

Si vous souhaitez définir un ID unique de 24 octets pour ces propriétés, consultez la section Pour créer un ID unique de 24 octets pour les messages envoyés à MQSeries.

Pour créer un ID unique de 24 octets pour les messages envoyés à MQSeries

Créez un projet de bibliothèque de classes C# dans Visual Studio.

Collez le code suivant dans le fichier .cs de la classe :

using System;  
using System.Collections.Generic;  
using System.Text;  
using System.Security.Cryptography;  

namespace MQId  
{[Serializable]  
    public class GetId  
    {  
        RNGCryptoServiceProvider randomCryptoString = new RNGCryptoServiceProvider();  

        public string getGuidstr()  
        {  
            byte[] newGuid = GetRandomData(24);  
            return ConvertToHex(newGuid);  
        }  

        private byte[] GetRandomData(int keySize)  
        {  
            byte[] randomData = new byte[keySize];  
            randomCryptoString.GetBytes(randomData);  
            return randomData;  
        }  

        private string ConvertToHex(byte[] key)  
        {  
            StringBuilder hexString = new StringBuilder();  
            for (int i = 0; i < key.Length; ++i)  
            {  
                hexString.Append(String.Format("{0:X2}", key[i]));  
            }  
            return hexString.ToString();  
        }  
    }  
}

Spécifiez un espace de noms par défautMQId et un nom d’assemblyde GetId dans la page Application des propriétés du projet.
Spécifiez un fichier de clé de nom fort pour signer l’assembly sur la page de signature des propriétés du projet, puis générez le projet.
Utilisez l’outil global assembly cache (gacutil.exe) pour charger l’assembly compilé dans le GAC (gacutil /i <name of compiled dll file>).
Ajoutez une référence à l'assembly GetId dans le projet BizTalk pour cet exemple.
Ajoutez deux variables à l'orchestration utilisée dans cet exemple :

Nom de la variable (identificateur) Type

GetId MQId.GetId

strGuid System.String

Nom de la variable (identificateur)	Type
GetId	MQId.GetId
strGuid	System.String

Collez le code suivant dans la forme Expression utilisée dans l'orchestration de cet exemple ; il doit remplacer le code existant :

GetId = new MQId.GetId();  
strGuid = GetId.getGuidstr();  
MQSeriesRequestSendMessageModified = MQSeriesRequestSendMessage;  
MQSeriesRequestSendMessageModified(MQSeries.MQMD_MsgId) = strGuid;  
MQSeriesRequestSendMessageModified(MQSeries.MQMD_CorrelId) = strGuid;

Arrêtez et supprimez l’orchestration dans la console d’administration BizTalk Server si elle est déjà déployée. Suivez ensuite les étapes des sections Génération et déploiement de cet exemple, Lier et démarrer l’orchestration et Tester l’application.

Notes

L'utilisation de cette méthode pour créer un ID unique de 24 octets pour les messages envoyés à MQSeries ne garantit pas à 100 % l'unicité des ID pour l'ensemble des messages, mais la probabilité d'ID de message en double est très faible. Si vos contraintes professionnelles nécessitent une garantie à 100 % de l'absence de doublons parmi les ID de message, vous devrez opter pour un code personnalisé différent pour atteindre cet objectif.

Classes ou méthodes utilisées dans l'exemple

Cet exemple ne fait pas un usage explicite des classes ou des méthodes.

Voir aussi

Corrélation de messages dans un scénario de requête-réponse
Exemples d’adaptateurs MQSeries

Partager via