Transaktionaler Adapter (BizTalk Server-Beispiel)

Artikel
07/21/2023

Im Transaktionsadapterbeispiel wird veranschaulicht, wie während der Verarbeitung einer BizTalk Server Nachricht eine explizite MsDTC-Transaktion (Microsoft Distributed Transaction Coordinator) für eine Datenbank erstellt und verwendet wird.

Ziel des Beispiels

Dieses Beispiel enthält einen Empfangsadapter, der in einem benutzerdefinierten Intervall eine SQL-Anweisung ausführt, um mithilfe einer MSDTC-Transaktion Daten aus einer SQL Server-Datenbank abzurufen. Die Daten werden dann in Form einer Nachricht im Kontext derselben Transaktion an die BizTalk Server MessageBox-Datenbank übermittelt.

Der entsprechende Sendeadapter führt eine vom Benutzer angegebene gespeicherte SQL-Prozedur mit einer Eingabe aus einer BizTalk-Nachricht im Kontext einer Transaktion aus. Im Rahmen derselben Transaktion wird anhand bestimmter Daten aus der Nachricht die entsprechende Nachricht in der MessageBox-Datenbank gesucht und gelöscht.

Wie dieses Beispiel gestaltet ist und warum

Die Projektmappe in diesem Beispiel beinhaltet zwei Projekte. Das erste ist das administrative Projekt (Admin), das vor der Laufzeit verwendet wird, damit der Benutzer die Empfangsspeicherorte und Sendeports konfigurieren kann, von denen dieser Adapter verwendet wird. Das zweite ist das Laufzeitprojekt (Runtime), das ausgeführt wird, wenn der Sende- und der Empfangsadapter ausgeführt werden.

Speicherort dieses Beispiels

Das Beispiel ist im folgenden SDK-Verzeichnis gespeichert:

<Beispielpfad>\Samples\AdaptersDevelopment\TransactionalAdapter. Das administrative Konfigurationsprojekt befindet sich im Ordner "\Admin" und das Laufzeitprojekt im Ordner "\Runtime".

In der folgenden Tabelle werden die Dateien in diesem Beispiel samt Zweck beschrieben.

Dateiname des administrativen Projekts	Dateibeschreibung des administrativen Projekts
TransactionalAdmin.csproj	Datei für das administrative Projekt für den Adapter, die für die Konfiguration vor der Laufzeit verwendet wird
TransactionalReceiveHandler.xsd	XSD für die Eigenschaften des Empfangshandlers
TransactionalReceiveLocation.xsd	XSD für die Eigenschaften des Empfangsspeicherorts
TransactionalTransmitLocation.xsd	XSD für die Eigenschaften des Übertragungsspeicherorts
TransactionalTransmitHandler.xsd	XSD für die Eigenschaften des Übertragungshandlers
TransactionalAdapterManagement.cs	Konfigurationsverwaltung für den Adapter. Enthält GetConfigSchema, die von BizTalk Adapterframework aufgerufen wird, damit ein XSD-Konfigurationsschema für jeden der (vier) unterstützten Konfigurationstypen zurückgegeben wird.

Dateiname des Laufzeitprojekts	Dateibeschreibung des Laufzeitprojekts
Transactional.csproj	Datei des Laufzeitprojekts für den Adapter
TransactionalAsyncBatch.cs	Asynchrone Implementierung der Sendekomponente des Adapters
TransactionalDeleteBatch.cs	Löscht einen Nachrichtenbatch und bestimmt, ob für eine Transaktion ein Commit- oder Abbruchvorgang ausgeführt wird
TransactionalProperties.cs	Extrahiert Konfigurationseigenschaften und legt diese fest
TransactionalReceiver.cs	Erstellt und verwaltet Empfangsendpunkte
TransactionalReceiverEndpoint.cs	Führt das eigentliche Warten oder Abrufen für die einzelnen Empfangsspeicherorte durch
TransactionalTransmitter.cs	Nimmt von der Messaging-Engine einen Nachrichtenbatch für die Übertragung an

Verwenden dieses Beispiels

Dieses Beispiel ist als Rahmen gedacht, den Sie beim Erstellen benutzerdefinierter Sende- und Empfangsadapter mit expliziten Transaktionen zugrunde legen können.

Erstellen und Initialisieren dieses Beispiels

Wichtig

Wenn die BizTalk-Installation eine 64-Bit-Installation ist oder der Speicherort der Installation geändert wurde, müssen OutboundAssemblyPath, InboundAssemblyPath und AdapterMgmtAssemblyPath entsprechend geändert werden.

Erstellen eines Schlüssels mit starkem Namen für das Transaktionsadapterbeispiel

Starten Sie die Visual Studio-Eingabeaufforderung.

Geben Sie an der Eingabeaufforderung Folgendes ein, und drücken Sie dann die EINGABETASTE:

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

Geben Sie an der Eingabeaufforderung Folgendes ein, und drücken Sie dann die EINGABETASTE:
```
sn –k TransactionalAdapter.snk  
```
Geben Sie an der Eingabeaufforderung exit ein, und drücken Sie dann die EINGABETASTE, um das Eingabeaufforderungsfenster zu schließen.

Erstellen der Transaktionsadapterlösung

Klicken Sie auf Start, zeigen Sie auf Alle Programme, zeigen Sie auf Zubehör, und klicken Sie dann auf Windows Explorer.
Navigieren Sie zu \Programme (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter, und doppelklicken Sie auf TransactionalAdapter.sln, um diese Projektmappe in Visual Studio zu öffnen.
Um beide Transaktionsadapterprojekte (Admin und Runtime) in Projektmappen-Explorer zu erstellen, klicken Sie mit der rechten Maustaste auf ProjektmappentransaktionalAdapter, und klicken Sie dann auf Neu erstellen.

Ausführen dieses Beispiels

Registrieren des Transaktionsadapters

Navigieren Sie in Windows Explorer zu \Programme (x86)\Microsoft BizTalk Server <VERSION>SDK\Samples\AdaptersDevelopment\TransactionalAdapter\Admin.
Um die Transaktionsadapterdaten zur Registrierung hinzuzufügen, doppelklicken Sie auf TransactionalAdmin.reg.

Hinweis

TransactionalAdmin.reg enthält hartcodierte Pfade zu C:\Programme\Microsoft BizTalk Server\. Wenn Sie BizTalk Server nicht am Standardspeicherort installiert haben oder ihre BizTalk Server Installation von einer früheren Version aktualisiert haben, müssen Sie die Datei TransactionalAdmin.reg mit den entsprechenden Pfaden ändern. Aktualisieren Sie die den Werten InboundAssemblyPath, OutboundAssemblyPath und AdapterMgmtAssemblyPath zugeordneten Pfade, sodass auf den richtigen Speicherort der angegebenen Dateien verwiesen wird.

Wichtig

Wenn Sie BizTalk auf einem 64-Bit-Computer installieren, ändern Sie alle Instanzen des HKEY_CLASSES_ROOT\CLSID\ Registrierungseintrags in HKEY_CLASSES_ROOT\Wow6432Node\CLSID\ in der Registrierungsdatei TransactionalAdmin.reg .
Klicken Sie im Dialogfeld Registrierungs-Editor auf Ja , um den Beispieladapter zur Registrierung hinzuzufügen, und klicken Sie dann auf OK.
Klicken Sie zum Schließen von Windows Explorer auf Datei und dann auf Schließen.

Hinzufügen des transaktionalen Adapters zu BizTalk Server

Klicken Sie auf das Menü Start, wählen Sie Alle Programme, Microsoft BizTalk Server 20xx und dann BizTalk Server Verwaltung aus.
Erweitern Sie im BizTalk Server Administration die Struktur BizTalk Server Administration, erweitern Sie die BizTalk-Gruppenstruktur und dann die Struktur Plattformeinstellungen.
Klicken Sie mit der rechten Maustaste auf Adapter, klicken Sie auf Neu, und klicken Sie dann auf Adapter.

Gehen Sie im Dialogfeld Adaptereigenschaften wie folgt vor.

Option	Aufgabe
Name	Geben Sie TransactionalAdapter ein.
Adapter	Wählen Sie in der Dropdownliste Txn aus. Dieser Eintrag wird angezeigt, weil die Datei TransactionalAdmin.reg zuvor ausgeführt wurde.
BESCHREIBUNG	Geben Sie Beispieltransaktionsadapter ein.

Klicken Sie auf OK. Der Adapter wird jetzt in der Liste der Adapter im rechten Fenster der BizTalk-Verwaltungskonsole angezeigt.

Erstellen eines Empfangsports und -speicherorts, für die der Adapter verwendet wird

Erweitern Sie den Knoten BizTalk-Gruppe[Servername] in BizTalk Server-Verwaltung, erweitern Sie den Knoten Anwendungen, und erweitern Sie den Knoten BizTalk-Anwendung 1.
Klicken Sie mit der rechten Maustaste auf Empfangsports, und klicken Sie dann auf Neu, und wählen Sie Unidirektionalen Empfangsport aus.
Geben Sie unter NameTxnReceivePort1 ein, und klicken Sie dann auf OK.
Klicken Sie mit der rechten Maustaste auf den Knoten Empfangsorte , klicken Sie auf Neu, und wählen Sie dann Unidirektionale Empfangsadresse aus.
Wählen Sie im DialogfeldEmpfangsport auswählendie Option TxnReceivePort1 aus, und klicken Sie dann auf OK.
Geben Sie im Dialogfeld Eigenschaften des Empfangsspeicherorts auf der Registerkarte Allgemeinden Namen TxnReceiveLocation1ein. Stellen Sie sicher, dass die Bezeichnung EmpfangsportTxnReceivePort1 anzeigt.
WählenSie im Dropdownfeld Typ im Transportframedie Option TransactionalAdapter aus.
Stellen Sie im Feld Empfangspipeline sicher, dass PassThruReceive ausgewählt ist. Übernehmen Sie für die übrigen Eigenschaften die Standardeinstellungen.

Klicken Sie neben dem Dropdownfeld Typ auf die Schaltfläche Konfigurieren. Daraufhin wird ein Dialogfeld speziell für diesen Adapter angezeigt. Geben Sie folgendes an, wie sie angezeigt werden, und klicken Sie dann auf OK.

Eigenschaft	Einstellung
Verbindungszeichenfolge	Die SQL-Datenbankverbindungszeichenfolge, die zum Herstellen einer Verbindung mit der Northwind-Datenbank und zur Authentifizierung bei der Datenbank verwendet wird. Später wird ein SQL-Skript ausgeführt, in dem diese Datenbank genutzt wird.
Befehlstext	Die SQL-Anweisungen, die für die Northwind-Datenbank ausgeführt werden, um Daten abzurufen, die dann in eine BizTalk-Nachricht eingefügt werden sollen.
Cookie	Umfasst einen Teil des URI. Geben Sie also einen eindeutigen Wert ein, z. B. den Namen des Empfangsspeicherorts. Beispiel: TxnReceiveLocation1.
Einheit des Abrufintervalls	Die Einheiten der Zeitmessung für den Abruf der Daten. Legen Sie hier Sekunden fest.
Abrufintervall	Die Anzahl der Einheiten der Zeitmessung für den Abruf der Daten. Legen Sie hier 15 Sekunden fest.

Klicken Sie auf OK, um das Dialogfeld Konfigurieren zu schließen, und dann erneut AUF OK, um das Dialogfeld Eigenschaften des Empfangsspeicherorts zu schließen, um zur BizTalk Server Verwaltung zurückzukehren.

Erstellen eines Sendeports und eines Sendehandlers, für die der Adapter verwendet wird

Wenn der Knoten BizTalk Application 1 noch erweitert ist, klicken Sie mit der rechten Maustaste auf Ports senden, klicken Sie dann auf Neu, und wählen Sie Static One-Way Sendeport aus.
Geben Sie im Feld Nameden Namen TxnSendPort1 ein.
Wählen Sie im Transportframe in der Dropdownliste Typdie Option TransactionalAdapter aus..
Stellen Sie im Feld Pipeline senden sicher, dass PassThruTransmit ausgewählt ist.

Klicken Sie neben der Dropdownliste Transport auf die Schaltfläche Konfigurieren. Geben Sie im angezeigten Dialogfeld folgendes an, wie Sie es angezeigt haben, und klicken Sie dann auf OK.

Eigenschaft	Einstellung
Cookie	Enthält einen Teil des URI: Geben Sie hier einen eindeutigen Wert ein, z. B. den Namen des Empfangsspeicherorts für instance: TxnSendPort1.
Verbindungszeichenfolge	Die SQL-Datenbankverbindungszeichenfolge, die zum Herstellen einer Verbindung mit der Northwind-Datenbank und zur Authentifizierung bei der Datenbank verwendet wird. Es ist wahrscheinlich derselbe, der zum Konfigurieren des TxnReceiveLocation1-Empfangsspeicherorts verwendet wird.
Gespeicherte Prozedur	Der Name der gespeicherten Prozedur, der ausgeführt wird, um die Datenbank abzufragen – sp_txnProc. Der Text der BizTalk-Nachricht wird dieser gespeicherten Prozedur als Zeichenfolgenparameter namens @Datazugewiesen. Beispielsweise konfiguriert der Benutzer in diesem Fall später die gespeicherte Prozedur mit dem Namen sp_txnProc. Zur Laufzeit des Adapters wird das Äquivalent dieses Aufrufs an die Datenbank ausgeführt. exec sp_txnProc @Data = "der Inhalt der BizTalk-Nachricht"

Klicken Sie im linken Navigationsbereich auf Filter.
Geben Sie im Editor für Filterausdrücke den folgenden Ausdruck ein, um ein Abonnement für diesen Sendeport einzurichten, damit Nachrichten empfangen werden, die am Empfangsport TxnReceivePort1 eingehen.

Geben Sie die folgenden Werte ein:BTS. ReceivePortName== TxnReceivePort1
1. (property)BTS. ReceivePortName
2. (operator) ==
3. (value)TxnReceivePort1
Verwenden Sie die Standardwerte für den Rest der Adaptereigenschaften, und wählen Sie OK aus.

Ausführen des Beispiels

Klicken Sie auf Start, zeigen Sie auf Alle Programme, zeigen Sie auf Microsoft SQL Server 2008 R2, und wählen Sie SQL Server Management Studio aus.
Stellen Sie im Dialogfeld Verbindung mit Server herstellen sicher, dass Servertyp auf Datenbank-Engine festgelegt ist, und geben Sie Anmeldeinformationen ein, um sich beim Datenbankserver zu authentifizieren, und wählen Sie dann Verbinden aus.

Wählen Sie die Symbolleistenschaltfläche Neue Abfrage aus, und fügen Sie Folgendes in das neue Abfragefenster ein, um eine Testtabelle, Testdaten und eine gespeicherte Testprozedur in die Northwind-Datenbank einzufügen. Wählen Sie die Symbolleistenschaltfläche Ausführen aus.

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

Erweitern Sie in BizTalk Server Verwaltung den Knoten Sendeports, wählen Sie den Sendeport TxnSendPort1 aus, und wählen Sie Start aus.
Erweitern Sie in BizTalk Server Verwaltung den Knoten ReceiveLocations, wählen Sie den Empfangsspeicherort TxnReceiveLocation1 und dann Aktivieren aus.
Nach dem Aktivieren des Empfangsspeicherorts werden in den angegebenen Intervallen Daten aus der Datenbank abgerufen.

Im Beispiel verwendete Klassen oder Methoden

IBTTransmitterBatch-Schnittstelle (COM)
IBTTransportProxy-Schnittstelle (COM)

Diese Methoden werden in der Referenz zu API-Namespaces für Entwickler und benutzeroberflächenleitfadend beschrieben.

Weitere Informationen

Adapterbeispiele – Entwicklung
Registrieren eines Adapters

Freigeben über