When your business process moves outside of BizTalk Server—into a Web API, a Windows Service, or a custom portal—you can no longer use the Tracking Profile Editor (TPE). To maintain visibility, you must use the BAM API.
To use the BAM API, you first need to understand the core objects located in the Microsoft.BizTalk.Bam.EventObservation namespace.
The EventStream Class
The EventStream class is the abstract base for sending information to the BAM database. There are two primary implementations you will use, depending on your performance and consistency needs.
The BAM API defines four main classes:
- DirectEventStream: used in a .NET application to do a buffered write of data to BAM.
- BufferedEventStream: used in a .NET application to do an unbuffered write of data to BAM.
- OrchestrationEventStream: used when writing to BAM programmatically within an orchestration; Provides transactional consistency with the orchestration.
- MessagingEventStream: used when writing to BAM programmatically within a pipeline; Provides transactional consistency with the messaging engine.
All of these classes are derived from the base class EventStream.
📝 One-Minute Brief
While the Tracking Profile Editor (TPE) is the standard for BizTalk, the BAM API is the key to tracking events from external .NET applications. This guide breaks down the essential objects in the Microsoft.BizTalk.Bam.EventObservation namespace, including the DirectEventStream for synchronous tracking and the BufferedEventStream for high-performance, asynchronous scenarios. Master these objects to integrate non-BizTalk processes into your BAM activities seamlessly.
Differences between BufferedEventStream and DirectEventStream
- BufferedEventStream: The
BufferedEventStreamis designed for high-performance enterprise applications. It stores the tracking data in the BizTalkMsgBoxDb first, and the “BAM Event Bus” service moves it to the BAM database later.- Is asynchronous
- When you update a BufferedEventStream, the update is cached and written later.
- The BufferedEventStream takes advantage of the cache to improve performance
- Best for: High-volume applications where you don’t want tracking to impact the performance of the main business logic.
- Risk: There is a slight delay (latency) before data appears in the BAM Portal.
- DirectEventStream: The
DirectEventStreamwrites data directly to theBAMPrimaryImportdatabase in real-time.- Is synchronous
- When you execute an update, the call won’t return until the database write is committed
- If your application cannot afford to lose data in a server crash, use this class
- Best for: Scenarios where data must be visible in the BAM Portal immediately.
- Risk: If the SQL Server is slow or down, your application will wait (synchronous) and potentially time out.
Advantages of using OrchestrationEventStream
- Performance: It can piggyback its database writes on the orchestration persistence points for maximum performance
- Consistency: because it writes during orchestration persistence points, even in the event of the server crash, the state of the orchestration recorded by BAM is guaranteed to be consistent with the last orchestration persistence point
Choosing the right BAM API object is a balance between performance and visibility. By using BufferedEventStream, you ensure that your monitoring logic never becomes a bottleneck for your business applications.
