BizTalk BAM : Writing Event Data

Instrumenting a BizTalk application with BAM is easy. Simply create a new class library, add a reference to Microsoft.BizTalk.Bam.EventObservation.dll, and add a reference to Microsoft.BizTalk.Pipeline.dll to support the IPipelineContext and IBaseMessage parameters on the below sample “WriteEvent” method.

public void WriteEvent(IPipelineContext context, IBaseMessage msg)
            // BufferedEventStream is an asynchonrous call that writes the BAM event data direct
            // to the messagebox.  There is latency here in that the BAMPrimaryImport tables will
            // be updated by TDDS.  However run time performance is fast due to the asyc no wait call.
            Microsoft.BizTalk.Bam.EventObservation.EventStream bamEventStream =
                new Microsoft.BizTalk.Bam.EventObservation.BufferedEventStream("Integrated Security=SSPI;Data Source=.;Initial Catalog=BizTalkMsgBoxDb", 1);

            // DirectEventStream is a synchronous call to the BAMPrimaryImport database.
            // There is no latency in populating BAM here.  Data is inserted directly
            // into the BAM activity tables and the call waits for a response to acknowledge
            // the BAM event data has been committed
            //Microsoft.BizTalk.Bam.EventObservation.EventStream bamEventStream =
            //    new Microsoft.BizTalk.Bam.EventObservation.DirectEventStream("Integrated Security=SSPI;Data Source=.;Initial Catalog=BAMPrimaryImport", 1);

            // MessagingEventStream is an asynchronous call that participates in the pipeline
            // context transaction.  Essentially this means if the pipeline fails the BAM
            // event will not be commited to the BAM Activity tables in the
            // BAMPrimaryImport database.
            //Microsoft.BizTalk.Bam.EventObservation.EventStream bamEventStream =
            //                                                context.GetEventStream();

            //Microsoft.BizTalk.Bam.EventObservation.EventStream bamEventStream = context.GetEventStream();
            string activityId = System.Guid.NewGuid().ToString();
            string activityName = "SalesOrder";

            // Begin the BAM activity by assigning a unique activity id, in this case a guid
            bamEventStream.BeginActivity(activityName, activityId);

            // Update the activity with some data sales order information
            bamEventStream.UpdateActivity(activityName, activityId,
                "SalesOrderId", "1234",
                "SalesPersonId", "MJAK6",
                "SaleNote", "Stock on hand");

            // Complete the activity
            bamEventStream.EndActivity(activityName, activityId);

In the above sample code we can see usage of BuffererEventStream, DirectEventStream, and MessagingEventStream which operates under the pipeline context. There is a fourth option, OrchestrationEventStream. To use this simply create a BizTalk project, add a reference to Microsoft.Biztalk.BAM.Xlangs.dll, and add the below code to an expression shape.

Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity("SalesOrder", activityId);

So the next question is when to use what.

  • Use OrchestrationEventStream from within BizTalk Orchestrations
  • Use MessagingEventStream when you want BAM to participate in the pipeline context transaction
  • Use BufferedEventStream for ultimate run time performance when you do not want to participate in a pipeline context transaction.  BufferedEventStream commits data to the BizTalkMsgBox database which is then shipped to the BAMPrimaryImport database by TDDS.  There is slight latency in BAM activity tables being updated due to the TDDS running on a scheduled basis.  The same asynchronous model applies to OrchestrationEventStream and MessagingEventStream.
  • Use DirectEventStream when you want to insert data direct into BAM and handle any errors.  So if BAM is mission critical and for example a message should not be processed if BAM is out of action.  Note this is a synchronous call and will impact run time performance.  The call waits until BAM data has been commited to the BAMPrimaryImport BAM activity tables.
This entry was posted in BizTalk Server. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s