Strumentazione di una soluzione: procedura dettagliata per l'utilizzo dell'API
In questo argomento viene descritta la procedura di strumentazione di un'applicazione mediante la classe API BAM. Nei frammenti di codice riportati di seguito il codice di esempio è stato semplificato utilizzando costanti e il codice minimo necessario per eseguire la strumentazione dell'applicazione.
Il frammento di codice seguente mostra come creare un nuovo oggetto Microsoft.BizTalk.Bam.EventObservation.EventStream , in particolare un oggetto Microsoft.BizTalk.Bam.EventObservation.DirectEventStream. In questo frammento il primo parametro specifica la stringa di connessione all'archivio dati del database di importazione primaria BAM e il secondo parametro specifica la frequenza con cui gli eventi vengono scritti nell'archivio dati.
Nota
BAM supporta le connessioni solo agli archivi dati SQL Server. La stringa di connessione di esempio rappresenta la stringa minima necessaria per stabilire una connessione. La configurazione specifica potrebbe richiedere parametri aggiuntivi da specificare nella stringa di connessione.
Se il valore di FlushThreshold è 0, gli eventi non vengono scritti automaticamente ma soltanto chiamando il metodo Flush. Se invece il valore è 1, ogni evento verrà scritto quando si verifica. I valori maggiori di 1 specificano che gli eventi vengono scritti quando si verifica un batch dell'accumulo specificato. L'utilizzo di un valore maggiore di 1 può contribuire a migliorare le prestazioni.
// 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);
Dopo aver creato l'oggetto [Microsoft.BizTalk.Bam.EventObservation.EventStream]/dotnet/api/microsoft.biztalk.bam.eventobservation.eventstream, è possibile iniziare l'attività e iniziare ad aggiornare la tabella attività con le attività raccolte e i dati. Quando è stata distribuita l'attività BAM, nel database di importazione primaria BAM sono state create cinque tabelle. Per ulteriori informazioni sul processo di sviluppo, vedere Overview of the BAM Development Process.
La chiamata del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity aggiunge un record alla tabella bam_ PurchaseOrder_Activity. Il primo parametro contiene il nome dell'attività che viene aggiornata e il secondo parametro contiene un identificatore per l'istanza dell'attività. L'identificatore può essere qualsiasi stringa, ma deve essere univoco nell'ambito del set di record dell'attività.
In questa fase il record non contiene alcun dato. Il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity aggiorna il record con i dati degli eventi acquisiti. Ancora una volta è necessario specificare un'attività e l'identificatore di istanza dell'attività. Passare le coppie nome/valore del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity delle attività cardine e degli elementi dati definiti nell'attività. Si supponga, ad esempio, che l'attività abbia definito un'attività cardine MS_Received. Quando l'attività è stata distribuita, nella tabella bam_ PurchaseOrder_Activity è stata creata una colonna per l'attività cardine. La chiamata al metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity specifica la coppia nome/valore di MS_Received e DateTime.UtcNow per aggiornare l'attività con i dati ricevuti per l'ordine di acquisto.
// 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 questo esempio si continua con una seconda attività. Per ulteriori informazioni sulle continuazioni, vedere Activity Continuation.
Per consentire ad altre applicazioni instrumentate di aggiornare l'attività PurchaseOrder, è necessario includere una chiamata al metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation . La chiamata specifica l'attività a cui possono contribuire altre applicazioni, l'identificatore dell'istanza dell'attività che viene rilevata e il token di continuazione che verrà utilizzato da altre applicazioni per aggiornare l'attività. Per rilevare lo stato della continuazione viene scritto un record nella tabella bam_ PurchaseOrder_continuations. Se l'attività continua con altri processi, per ogni chiamata al metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation viene scritto un record con un token di continuazione univoco.
Importante
Ogni segmento di codice in uno scenario di continuazione deve includere la propria chiamata del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity . In caso contrario, il record attività verrà tralasciato o risulterà orfano.
Tuttavia, solo il primo segmento (che usa l'ID attività effettivo) include il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity , mentre tutti gli altri segmenti (che usano il proprio ID token univoco) non devono chiamare il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity
Una volta chiamato il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation , altri componenti possono aggiornare l'attività ordine di acquisto mediante Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity , specificando il token di continuazione invece dell'ID attività. Quando gli altri componenti completano le proprie attività, ogni componente deve chiamare Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity con il token di continuazione per informare l'infrastruttura BAM che non sono previsti altri eventi.
Importante
Una volta chiamato il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation , è possibile che un'attività diventi orfana se il processo in cui viene continuata l'attività non chiama mai un metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity con il token di continuazione.
// Continue the activity to the next process that has been
// instrumented to handle the continuation.
es.EnableContinuation("PurchaseOrder", “PO123”, “AP123”);
Infine, l'attività viene finalizzata con una chiamata del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity specificando il nome e l'identificatore dell'attività. Se non sono presenti continuazioni non completate, l'attività viene spostata nella tabella bam_ PurchaseOrder _completed. Se le attività di continuazione non vengono completate, è possibile che le attività diventino orfane.
// Activity from this segment (PO submission) is completed
es.EndActivity("PurchaseOrder", “PO123”);
Quando l'attività continua in processi separati, l'applicazione viene instrumentata per aggiornare la tabella delle attività con una chiamata del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.UpdateActivity specificando il nome dell'attività e il token di continuazione dichiarato nella chiamata del metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EnableContinuation .
Nota
Il processo che gestisce l'attività continuata non chiama il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity . Il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.BeginActivity crea un'istanza dell'attività generando le tabelle nel database di importazione primaria BAM. Il processo su cui viene continuata l'attività aggiorna l'istanza dell'attività già esistente.
// 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);
Parte del flusso di lavoro di questo esempio di codice specifica un riferimento, in questo caso un tipo specifico di riferimento, ovvero un'attività correlata. Se si specifica un'attività correlata, viene creato un collegamento dall'attività primaria ad altre attività che possono risultare utili all'utente che visualizza l'attività nel portale BAM.
La chiamata al metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.AddRelatedActivity scrive un record nella tabella bam_ PurchaseOrder_ActiveRelationships collegando le attività.
// 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”);
Per terminare l'attività continuata, è necessario chiamare il metodo Microsoft.BizTalk.Bam.EventObservation.EventStream.EndActivity specificando il token di continuazione per la continuazione da terminare. Se non sono presenti altre continuazioni non completate, l'attività ordine di acquisto viene spostata nella tabella bam_ PurchaseOrder _completed.
// Activity from this segment (ApprovalProcess) is completed
es.EndActivity("PurchaseOrder", “AP123”);
Esempio di codice completo
//---------------------------------------------------------------------
// 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.
}
}