Instrumentieren einer Lösung: Schritt-für-Schritt-Anleitung zur Verwendung der API
In diesem Thema wird beschrieben, wie eine Anwendung mithilfe der BAM-API-Schlüsselklasse instrumentalisiert wird. Die folgenden Codeausschnitte enthalten einen vereinfachten Beispielcode, bei dem Konstanten und nur der zum Instrumentieren einer Anwendung erforderliche Code verwendet wurden.
Der folgende Codeausschnitt veranschaulicht, wie Sie ein neues Microsoft.BizTalk.Bam.EventObservation.EventStream -Objekt, insbesondere vom Typ Microsoft.BizTalk.Bam.EventObservation.DirectEventStream, erstellen. In diesem Ausschnitt enthält der erste Parameter die Verbindungszeichenfolge für den Datenspeicher der primären BAM-Importdatenbank und der zweite Parameter gibt an, wie häufig die Ereignisse in den Datenspeicher geschrieben werden.
Hinweis
BAM unterstützt nur Verbindungen mit SQL Server Datenspeichern. Die in diesem Beispiel verwendete Verbindungszeichenfolge ist die kürzeste Variante, die zum Herstellen einer Verbindung erforderlich ist. Je nach Konfiguration müssen weitere Parameter in der Verbindungszeichenfolge angegeben werden.
Ein FlushThreshold -Wert von 0 gibt an, dass Ereignisse nicht automatisch geschrieben werden und dass zum Schreiben der Ereignisse die Flush-Methode aufgerufen werden muss. Bei einem Wert von 1 wird jedes Ereignis geschrieben, sobald es eintritt. Bei Werten größer als 1 werden Ereignisse geschrieben, wenn sich ein Batch der angegeben Größe angesammelt hat. Die Verwendung von Werten größer als 1 kann helfen, die Leistung zu verbessern.
// Specify the DES connection string.
const string connBAMPIT =
"Integrated Security=SSPI;server=.;database=BAMPrimaryImport";
// Write the activity update data on every call.
int flushThreshold = 1;
// Create a DES instance
EventStream es =
new DirectEventStream(connBAMPIT, flushThreshold);
Nachdem das Objekt [Microsoft.BizTalk.Bam.EventObservation.EventStream]/dotnet/api/microsoft.biztalk.bam.eventobservation.eventstream) erstellt wurde, können Sie mit der Aktivität beginnen und die Aktivitätstabelle mit den gesammelten Meilensteinen und Daten aktualisieren. Beim Bereitstellen der BAM-Aktivität wurden fünf Tabellen in der primären BAM-Importdatenbank erstellt. Weitere Informationen zum Entwicklungsprozess finden Sie unter Overview of the BAM Development Process.
Durch das Aufrufen der Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity -Methode wird der Bam_ PurchaseOrder_Activity-Tabelle ein Datensatz hinzugefügt. Der erste Parameter enthält den Namen der Aktivität, die aktualisiert wird, und der zweite Parameter enthält einen Bezeichner für diese Instanz der Aktivität. Der Bezeichner kann aus einer beliebigen Zeichenfolge bestehen, die jedoch im Datensatz für die Aktivität eindeutig sein muss.
Zu diesem Zeitpunkt enthält der Datensatz keine Daten. Die Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity -Methode aktualisiert den Datensatz anhand der aufgezeichneten Ereignisdaten. Sie geben erneut eine Aktivität und den Bezeichner für die Aktivitätsinstanz an. Übergeben Sie der Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity -Methode Name-Wert-Paare aus Datenelementen und Meilensteinen, die Sie in der Aktivität definiert haben. Die hier als Beispiel angeführte Aktivität hat einen Meilenstein namens MS_Received definiert. Beim Bereitstellen der Aktivität wurde für den Meilenstein eine Spalte in der Tabelle bam_ PurchaseOrder_Activity erstellt. Durch den Aufruf der Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity -Methode wird das Name-Wert-Paar aus MS_Received und DateTime.UtcNow angegeben, um die Aktivität mit dem Empfangsdatum für die Bestellung zu aktualisieren.
// When a purchase order is received, you call the
// BeginActivity method in the receive application.
// You can then capture the event data by calling
// the UpdateActivity method.
es.BeginActivity ("PurchaseOrder", "PO123");
es.UpdateActivity ("PurchaseOrder", "PO123",
"MS_Received", DateTime.UtcNow,
"T_Customer", "Joe");
In diesem Beispiel erfolgt die Fortsetzung mit einer zweiten Aktivität. Weitere Informationen zu Konfigurationen finden Sie unter Activity Continuation.
Wenn Sie weitere instrumentierte Anwendungen zum Aktualisieren der PurchaseOrder-Aktivität aktivieren möchten, fügen Sie einen Aufruf der Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation -Methode hinzu. Der Aufruf gibt die Aktivität an, an der andere Anwendungen mitwirken können, den Bezeichner für die Instanz der zu überwachenden Aktivität und das Fortsetzungstoken, mit dem andere Anwendungen die Aktivität aktualisieren können. In die Tabelle bam_ PurchaseOrder_continuations wird ein Datensatz zum Überwachen des Status der Fortsetzung geschrieben. Wenn die Aktivität mit anderen Prozessen fortfährt, wird bei jedem Aufruf der Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation -Methode mit einem eindeutigen Fortsetzungstoken ein Datensatz geschrieben.
Wichtig
Jedes Codesegment in einem Fortsetzungsszenario benötigt einen eigenen Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity -Methodenaufruf. Wird die unterlassen, führt dies zu einem verwaisten Aktivitätsdatensatz.
Jedoch nur das erste Segment (das die tatsächliche Aktivitäts-ID verwendet) verfügt über die Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity -Methode, alle anderen Segmente (die ihre eigenen eindeutigen Token-ID verwenden), müssen die Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity -Methode nicht aufrufen.
Nachdem die Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation -Methode aufgerufen wurde, können andere Komponenten die Bestellungsaktivität mithilfe von Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity aktualisieren, indem sie das anstelle der Aktivitäts-ID das Fortsetzungstoken angeben. Nachdem die anderen Komponenten ihre Aufgaben abgeschlossen haben, muss jede der Komponenten Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity mit dem Fortsetzungstoken aufrufen, um die BAM-Infrastruktur darüber zu informieren, dass keine weiteren Ereignisse erwartet werden.
Wichtig
Sobald die Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation -Methode aufgerufen wird, kann es dazu kommen, dass eine Aktivität verwaist. Dies ist der Fall, wenn der Prozess, in dem die Aktivität fortgesetzt wird, nie eine Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity -Methode mit dem Fortsetzungstoken aufruft.
// Continue the activity to the next process that has been
// instrumented to handle the continuation.
es.EnableContinuation("PurchaseOrder", “PO123”, “AP123”);
Zum Schluss wird die Aktivität abgeschlossen, indem die Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity -Methode unter Angabe des Namens und des Bezeichners der Aktivität aufgerufen wird. Wenn keine nicht beendeten Fortsetzungen vorhanden sind, wird die Aktivität in die Tabelle bam_ PurchaseOrder _completed verschoben. Aktivitäten können verwaisen, wenn Fortsetzungsaktivitäten nicht abgeschlossen werden.
// Activity from this segment (PO submission) is completed
es.EndActivity("PurchaseOrder", “PO123”);
Wenn die Aktivität in einem separaten Prozess fortgesetzt wird, wird die Anwendung instrumentiert, um die Aktivitätstabelle durch Aufrufe von Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity zu aktualisieren. Dabei werden der Aktivitätsname und das Fortsetzungstoken angegeben, die im Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation -Methodenaufruf deklariert sind.
Hinweis
Durch den Prozess, der die fortgesetzte Aktivität verarbeitet, wird die Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity -Methode nicht aufgerufen. Die Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity -Methode erstellt eine Instanz der Aktivität, indem sie Tabellen in der primären BAM-Importdatenbank erstellt. Der Prozess, für den die Aktivität fortgesetzt wird, aktualisiert die Instanz der bereits vorhandenen Aktivität.
// update when the order is approved
es.UpdateActivity ("PurchaseOrder", “AP123”, "MS_Approved",
DateTime.UtcNow, "T_Product", "Widget");
// update when the product is ready for shipment
es.UpdateActivity ("PurchaseOrder", “AP123”,
"MS_Ready", DateTime.UtcNow);
Im Rahmen des Workflows für dieses Beispiel gibt der Code einen Verweis an, in diesen Fall einen bestimmten Typ von Verweis – eine verwandte Aktivität. Durch Angeben einer verwandten Aktivität erstellen Sie eine Verknüpfung aus der primären Aktivität zu anderen Aktivitäten, die für einen Benutzer, der die Aktivität im BAM-Portal anzeigt, von Interesse sind.
Durch den Aufruf der Microsoft.BizTalk.Bam.EventObservation.EventStream.AddRelatedActivity -Methode wird ein Datensatz in die bam_ PurchaseOrder_ActiveRelationships-Tabelle geschrieben, die die Aktivitäten verknüpft.
// These are shipped in two shipments.
// Relates the current purchase order
// instance to two shippings.
// Note: only one direction
es.AddRelatedActivity ("PurchaseOrder", “AP123”,
"Shipping", “UPS101”);
es.AddRelatedActivity ("PurchaseOrder", “AP123”,
"Shipping", “UPS102”);
Zum Beenden der fortgesetzten Aktivität wird die Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity -Methode aufgerufen, wobei das Fortsetzungstoken für die endende Fortsetzung angegeben wird. Wenn keine weiteren nicht beendete Fortsetzungen vorhanden sind, wird die Bestellungsaktivität in die Tabelle completed verschoben.
// Activity from this segment (ApprovalProcess) is completed
es.EndActivity("PurchaseOrder", “AP123”);
Vollständiges Codebeispiel
//---------------------------------------------------------------------
// File:BAMMinimalSample.cs
//
// Summary: Demonstrates how to instrument an application
//using BAM APIs to track useful information.
//
// Sample: BAM Api Sample
//
//---------------------------------------------------------------------
// This file is part of the Microsoft BizTalk Server SDK
//
// Copyright (c) Microsoft Corporation. All rights reserved.
//
// This source code is intended only as a supplement to Microsoft
// BizTalk Server release and/or on-line documentation. See
// these other materials for detailed information regarding Microsoft // code samples.
//
// THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF
// ANY KIND, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO // THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A
// PARTICULAR PURPOSE.
//---------------------------------------------------------------------
// This sample requires that you add the
// Microsoft.BizTalk.Bam.EventObservation.dll to the
// references in the Visual Studio Solution.
using System;
using System.Text;
using Microsoft.BizTalk.Bam.EventObservation;
namespace EventStreamSample
{
static void Main(string[] args)
{
//
// The following code would appear in a purchase order
// receipt application.
//
// Specify the DES connection string.
const string connBAMPIT =
"Integrated Security=SSPI;server=.;database=BAMPrimaryImport";
// Write the activity update data on every call.
int flushThreshold = 1;
// Create an instance of the DirectEventStream.
EventStream es =
new DirectEventStream(connBAMPIT, flushThreshold);
// When a purchase order is received, you call the
// BeginActivity method in the receive application.
// You can then capture the event data by calling
// the UpdateActivity method.
es.BeginActivity ("PurchaseOrder", "PO123");
es.UpdateActivity ("PurchaseOrder", "PO123",
"MS_Received", DateTime.UtcNow,
"T_Customer", "Joe");
// Continue the activity to the next process that has been
// instrumented to handle the continuation.
es.EnableContinuation("PurchaseOrder", “PO123”, “AP123”);
// Activity from this segment (PO submission) is completed
// end activity is synonymous to IsCompleted = 1
es.EndActivity("PurchaseOrder", “PO123”);
//
// The following code would typically appear in a separate
// application that monitors the approval process
// (ApprovalProcess.exe)
//
// update when the order is approved
es.UpdateActivity ("PurchaseOrder", “AP123”, "MS_Approved",
DateTime.UtcNow, "T_Product", "Widget");
// update when the product is ready for shipment
es.UpdateActivity ("PurchaseOrder", “AP123”,
"MS_Ready", DateTime.UtcNow);
// These are shipped in two shipments.
// Relates the current purchase order
// instance to two shippings.
// Note: only one direction
es.AddRelatedActivity ("PurchaseOrder", “AP123”,
"Shipping", “UPS101”);
es.AddRelatedActivity ("PurchaseOrder", “AP123”,
"Shipping", “UPS102”);
// Activity from this segment (ApprovalProcess) is completed
es.EndActivity("PurchaseOrder", “AP123”);
// In another Shipping application, two shipments with
ID’s UPS101 and UPS102 will be created.
}
}