Partager via

Adaptateur transactionnel (exemple BizTalk Server)

  • Article

L’exemple d’adaptateur transactionnel montre comment créer et utiliser une transaction MSDTC (Microsoft Distributed Transaction Coordinator) explicite sur une base de données pendant le traitement d’un message BizTalk Server.

Fonctions de l'exemple

Cet exemple contient un adaptateur de réception qui exécute une instruction SQL, à un intervalle spécifié par l'utilisateur, afin d'obtenir des données d'une base de données SQL Server à l'aide d'une transaction MSDTC. Les données sont ensuite envoyées à la base de données MessageBox BizTalk Server sous la forme d’un message dans le contexte de la même transaction.

L'adaptateur d'envoi correspondant exécute une procédure stockée SQL spécifiée par l'utilisateur via l'entrée d'un message BizTalk dans le contexte d'une transaction. Il utilise les données spécifiques de ce message pour localiser et supprimer le message correspondant de la base de données MessageBox, sous cette même transaction.

Comment cet exemple est conçu et pourquoi

Cet exemple inclut deux projets dans sa solution. Le premier, le projet administratif (Admin), est utilisé avant l'exécution pour permettre à un utilisateur de configurer les emplacements de réception et les ports d'envoi qui utilisent cet adaptateur. Le deuxième, le projet d'exécution (Runtime), est exécuté lorsque les adaptateurs d'envoi et de réception sont exécutés.

Accès à l'exemple

L'exemple se trouve dans l'emplacement SDK suivant :

<Chemin d’accès> des exemples\Samples\AdaptersDevelopment\TransactionalAdapter. Le projet administratif de configuration se trouve dans le dossier \Admin, et le projet d'exécution dans le dossier \Runtime.

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

Nom du fichier de projet Admin Description du fichier de projet Admin
TransactionalAdmin.csproj Fichier du projet administratif de l'adaptateur utilisé pour la configuration antérieure à l'exécution
TransactionalReceiveHandler.xsd XSD pour les propriétés du gestionnaire de réception
TransactionalReceiveLocation.xsd XSD pour les propriétés de l'emplacement de réception
TransactionalTransmitLocation.xsd XSD pour les propriétés de l'emplacement de transmission
TransactionalTransmitHandler.xsd XSD pour les propriétés du gestionnaire de transmission
TransactionalAdapterManagement.cs Gestion de la configuration de l'adaptateur. Contient GetConfigSchema qui est appelé par l'infrastructure d'adaptateurs BizTalk pour renvoyer un schéma de configuration XSD pour chacun des (quatre) types de configurations possibles qu'il prend en charge.
Nom du fichier de projet au moment de l'exécution Description du fichier de projet au moment de l'exécution
Transactional.csproj Fichier du projet d'exécution de l'adaptateur
TransactionalAsyncBatch.cs Implémentation asynchrone du port d'envoi de l'adaptateur
TransactionalDeleteBatch.cs Supprime un lot de messages et valide ou abandonne une transaction
TransactionalProperties.cs Extrait et définit les propriétés de configuration
TransactionalReceiver.cs Crée et gère les points de terminaison de réception
TransactionalReceiverEndpoint.cs Écoute réelle ou interrogation pour chaque emplacement de réception
TransactionalTransmitter.cs Accepte un lot de messages du moteur de messagerie à transmettre

Guide pratique pour utiliser cet exemple

Cet exemple est conçu comme une infrastructure que vous utilisez pour créer des adaptateurs d'envoi et de réception personnalisés à l'aide de transactions explicites.

Génération et initialisation de cet exemple

Important

Si l'installation BizTalk est 64 bits ou si son emplacement a été modifié, les valeurs OutboundAssemblyPath, InboundAssemblyPath, AdapterMgmtAssemblyPath doivent être modifiées en conséquence.

Créer une clé de nom fort pour l’exemple d’adaptateur transactionnel

  1. Démarrez l’invite de commandes Visual Studio.

  2. À l'invite de commandes, tapez la commande suivante, puis appuyez sur Entrée :

    cd \Program Files\Microsoft BizTalk Server <version>\SDK\Samples\AdaptersDevelopment\TransactionalAdapter\Runtime

  3. À l'invite de commandes, tapez la commande suivante, puis appuyez sur Entrée :

    sn –k TransactionalAdapter.snk

  4. À l’invite de commandes, tapez exit, puis appuyez sur Entrée pour fermer la fenêtre d’invite de commandes.

Générer la solution d’adaptateur transactionnel

  1. Cliquez sur Démarrer, pointez sur Tous les programmes, sur Accessoires, puis sur Windows Explorer.

  2. Accédez à \Program Files (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter, puis double-cliquez sur TransactionalAdapter.sln pour ouvrir cette solution dans Visual Studio.

  3. Pour générer les deux projets d’adaptateur transactionnel (Administration et runtime) dans Explorateur de solutions, cliquez avec le bouton droit sur Solution TransactionalAdapter, puis cliquez sur Reconstruire.

Exécution de cet exemple

Inscrire l’adaptateur transactionnel

  1. Dans Windows Explorer, accédez à \Program Files (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter\Administration.

  2. Pour ajouter les données de l’adaptateur transactionnel au Registre, double-cliquez sur TransactionalAdmin.reg.

    Notes

    TransactionalAdmin.reg inclut des chemins codés en dur vers C :\Program Files\Microsoft BizTalk Server\. Si vous n’avez pas installé BizTalk Server à l’emplacement par défaut ou si vous avez mis à niveau votre installation de BizTalk Server à partir d’une version précédente, vous devez modifier le fichier TransactionalAdmin.reg avec les chemins d’accès appropriés. Mettez à jour les chemins d'accès associés aux valeurs « InboundAssemblyPath », « OutboundAssemblyPath » et « AdapterMgmtAssemblyPath » afin qu'ils pointent vers l'emplacement correct des fichiers spécifiés.

    Important

    Si vous installez BizTalk sur un ordinateur 64 bits, remplacez toutes les instances de l’entrée de Registre HKEY_CLASSES_ROOT\CLSID\ par HKEY_CLASSES_ROOT\Wow6432Node\CLSID\ dans le fichier de Registre TransactionalAdmin.reg .

  3. Dans la boîte de dialogue Éditeur du Registre , cliquez sur Oui pour ajouter l’exemple d’adaptateur au Registre, puis cliquez sur OK.

  4. Pour fermer Windows Explorer, cliquez sur Fichier, puis sur Fermer.

Pour ajouter l'adaptateur transactionnel à BizTalk Server

  1. Cliquez sur le menu Démarrer, sélectionnez Tous les programmes, Microsoft BizTalk Server 20xx, puis BizTalk Server Administration.

  2. Dans l’BizTalk Server Administration, développez l’arborescence Administration BizTalk Server, l’arborescence BizTalk Group, puis l’arborescence Paramètres de plateforme.

  3. Cliquez avec le bouton droit sur Adaptateurs, cliquez sur Nouveau, puis sur Adaptateur.

  4. Dans la boîte de dialogue Propriétés de l’adaptateur, procédez comme suit.

    Propriété Pour
    Nom Tapez TransactionalAdapter.
    Adaptateur Sélectionnez Txn dans la liste déroulante. Cette entrée apparaît suite à l’exécution du fichier TransactionalAdmin.reg précédemment.
    Description Tapez Exemple d’adaptateur transactionnel.

  5. Cliquez sur OK. L’adaptateur apparaît maintenant dans la liste des adaptateurs dans la fenêtre de droite de la console Administration BizTalk.

Pour créer un port de réception et un emplacement qui utilise l'adaptateur

  1. Développez le nœud Groupe BizTalk[nom du serveur] dans BizTalk Server Administration, développez le nœud Applications, puis le nœud Application BizTalk 1.

  2. Cliquez avec le bouton droit sur Ports de réception, puis cliquez sur Nouveau, puis sélectionnez Port de réception unidirectionnel.

  3. Pour Nom, entrez TxnReceivePort1, puis cliquez sur OK.

  4. Cliquez avec le bouton droit sur le nœud Emplacements de réception, cliquez sur Nouveau, puis sélectionnez Emplacement de réception unidirectionnel.

  5. Dans la boîte de dialogueSélectionner un port de réception , sélectionnez TxnReceivePort1, puis cliquez sur OK.

  6. Dans la boîte de dialogue Propriétés de l’emplacement de réception, sous l’onglet Général , entrez TxnReceiveLocation1 comme Nom. Vérifiez que l’étiquette Port de réception affiche TxnReceivePort1.

  7. Dans la zone de liste déroulanteType , dans le cadre de transport , sélectionnez TransactionalAdapter.

  8. Dans la zone Pipeline de réception, vérifiez que PassThruReceive est sélectionné. Conservez les paramètres par défaut pour les propriétés restantes.

  9. Cliquez sur le bouton Configurer en regard de la zone de liste déroulante Type . Cela permet d'afficher une boîte de dialogue spécifique à cet adaptateur. Spécifiez ce qui suit comme vous le souhaitez, puis cliquez sur OK.

    Propriété Paramètre
    Chaîne de connexion Chaîne de connexion à la base de données SQL utilisée pour la connexion et l'authentification auprès de la base de données Northwind. Nous exécuterons ultérieurement un script SQL qui utilisera cette base de données.
    Texte de la commande Instructions SQL exécutées sur la base de données Northwind pour obtenir des données à placer dans un message BizTalk.
    Cookie Comprend une partie de l'URI. Entrez une valeur unique, telle que le nom de l'emplacement de réception ; par exemple, TxnReceiveLocation1.
    Unité intervalle d'interrogation Nombre d'unités de mesure de temps pour l'interrogation des données. Définissez cette propriété sur secondes.
    Fréquence d'interrogation Unité de mesure de temps pour l'interrogation des données. Définissez cette propriété sur 15 secondes.

  10. Cliquez sur OK pour fermer la boîte de dialogue Configurer, puis sur OK à nouveau pour fermer la boîte de dialogue Propriétés de l’emplacement de réception pour revenir à l’administration BizTalk Server.

Pour créer un port d'envoi et un gestionnaire d'envoi qui utilisent l'adaptateur

  1. Avec le nœud Application 1 BizTalk toujours développé, cliquez avec le bouton droit sur Ports d’envoi, puis cliquez sur Nouveau, puis sélectionnez Statique One-Way Port d’envoi.

  2. Dans le champ Nom , entrez TxnSendPort1.

  3. Dans le cadre transport , dans la liste déroulante Type , sélectionnezTransactionalAdapter.

  4. Dans la zone Envoyer le pipeline , vérifiez que PassThruTransmit est sélectionné.

  5. Cliquez sur le bouton Configurer en regard de la liste déroulante transport . Dans la boîte de dialogue qui s’affiche, spécifiez ce qui suit comme vous le souhaitez, puis cliquez sur OK.

    Propriété Paramètre
    Cookie Comprend une partie de l’URI : entrez ici une valeur unique, telle que le nom de l’emplacement de réception, pour instance : TxnSendPort1.
    Chaîne de connexion Chaîne de connexion à la base de données SQL utilisée pour la connexion et l'authentification auprès de la base de données Northwind. Il sera probablement le même que celui utilisé pour configurer l’emplacement de réception TxnReceiveLocation1 .
    Procédure stockée Nom de la procédure stockée exécutée pour interroger la base de données - sp_txnProc. Le corps du message BizTalk est donné à cette procédure stockée sous la forme d’un paramètre de chaîne appelé @Data. Par exemple, l’utilisateur configurera ultérieurement la procédure stockée avec le nom sp_txnProc. L'exécution de l'adaptateur exécuterait l'équivalent de cet appel à la base de données.

    exec sp_txnProc @Data = « le contenu du message BizTalk »

  6. Dans le volet de navigation gauche, cliquez sur Filtrer.

  7. Dans l'éditeur d'expression de filtre, entrez l'expression suivante pour définir un abonnement à ce port d'envoi et obtenir les messages reçus par le port de réception TxnReceivePort1.

    Entrez ces valeurs :BTS. ReceivePortName== TxnReceivePort1

    1. (property)BTS. ReceivePortName

    2. (operator) ==

    3. (value)TxnReceivePort1

  8. Utilisez les valeurs par défaut pour le reste des propriétés de l’adaptateur, puis sélectionnez OK.

Exécution de l'exemple

  1. Cliquez sur Démarrer, pointez sur Tous les programmes, pointez sur Microsoft SQL Server 2008 R2, puis sélectionnez SQL Server Management Studio.

  2. Dans la boîte de dialogue Se connecter au serveur , vérifiez que Type de serveur est défini sur Moteur de base de données, entrez les informations d’identification pour vous authentifier auprès du serveur de base de données, puis sélectionnez Se connecter.

  3. Sélectionnez le bouton de barre d’outils Nouvelle requête et collez ce qui suit dans la nouvelle fenêtre de requête pour insérer une table de test, des données de test et une procédure stockée de test dans la base de données Northwind. Sélectionnez le bouton Exécuter la barre d’outils.

    use [Northwind]  
GO  
if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[scratch]') and OBJECTPROPERTY(id, N'IsUserTable') = 1)  
drop table [dbo].[scratch]  
GO  
CREATE TABLE [dbo].[scratch] (  
     [id] [int] IDENTITY (1, 1) NOT NULL ,  
     [msg] [nvarchar] (4000) NOT NULL   
) ON [PRIMARY]  
GO  
GRANT SELECT , UPDATE , INSERT ON [dbo].[scratch] TO [public]  
GO  
if exists (select * from dbo.sysobjects where id = object_id(N'[dbo].[sp_txnProc]') and OBJECTPROPERTY(id, N'IsProcedure') = 1)  
drop procedure [dbo].[sp_txnProc]  
GO  
CREATE PROCEDURE [dbo].[sp_txnProc] @Data nvarchar (4000)  
AS   
INSERT scratch ( msg ) values ( @Data )  
GO  
GRANT EXECUTE ON [dbo].[sp_txnProc] TO [public]  
GO

  4. Dans BizTalk Server Administration, développez le nœud Ports d’envoi, sélectionnez le port d’envoi TxnSendPort1, puis sélectionnez Démarrer.

  5. Dans BizTalk Server Administration, développez le nœud ReceiveLocations, sélectionnez l’emplacement de réception TxnReceiveLocation1, puis sélectionnez Activer.

  6. Une fois l'emplacement de réception activé, il interroge automatiquement la base de données aux intervalles définis pour obtenir des données.

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

  • Interface IBTTransmitterBatch (COM)

  • Interface IBTTransportProxy (COM)

Ces méthodes sont décrites dans les instructions de l’interface utilisateur et les informations de référence sur l’espace de noms d’API des développeurs.

Voir aussi

Exemples d’adaptateurs- Développement
Inscription d’un adaptateur