BAM API: Using OrchestrationEventStream

  • Article

Since there is not much documentation* on this yet on how to use OrchestrationEventStream (an EventStream that is in synch with Orchestration), here is a quick info on the howto:

This new feature is found in Microsoft.BizTalk.Bam.XLANGs assembly.  From you BizTalk project, you can write the following in your orchestration, e.g. Expression Editor (click on the appropriate shape in orchestration to launch this):

// Sample code for using OrchestrationEventStream from an orchestration, no need to new it:
Microsoft.BizTalk.Bam.EventObservation.OrchestrationEventStream.BeginActivity( "PurchaseOrder", "PO123");

Note: this only applies to Biztalk 2006.

* To use this in Biztalk 2004 SP1, you will need a hot fix, its kb article can be found here: https://www.kbalertz.com/Feedback_900083.aspx,

Comments

  • Anonymous
    February 08, 2006
    So does this use the UpdateActivity? Also, when does this actually get sent to the MessageBox, (it goes to the MessageBoxDB, or does it go directly?). Also, what is the purpose of the Clear method, is it analagous to the flush? You state that you don't need to new it, however it is available, can you tell us in what situations you would need to use it?

  • Anonymous
    February 08, 2006
    OrchestrationEventStream is derived from EventStream, so all the other methods and properties of EventStream are available to OES.  The EventStream doc should provide you with all the informatation you need. Link:  
    http://msdn.microsoft.com/library/default.asp?url=/library/en-us/sdk/htm/frlrfmicrosoftbiztalkbameventobservationeventstreammemberstopic.asp

    When you write the code in Orchestration shape itself, such as an Expression Editor, the OES as shown in the above syntax would participate in the context of the Orchestration... meaning, internally the events submitted on this static OES class would be piggy-backing on the Orchestration buffer.  

    You would use this when you want consistency between Orchestration persistence and BAM persistence... in other words, if Orchestration throws an exception before reaching the next persistent point, any BAM event written since last persistent point would not be persisted as well.

    This is in contrast to using DirectEventStream or BufferedEventStream where once you have sent the event, it would get persited regardless if the Orchestration subsequently encounters an exception.

    Of all the EventStream, only DirectEventStream goes to BAMPrimaryImport directly. All the others, BES/MES/OES will be persisted to MessageBox first.

  • Anonymous
    February 08, 2006
    So then what is the context of the MES, it persists as long as the Message persists?

  • Anonymous
    February 09, 2006
    The comment has been removed

  • Anonymous
    January 02, 2007
    not related to this specific topic, but what is the advantage of MES over BES? what exactly is meant by participating in pipeline transaction, thanks

  • Anonymous
    January 08, 2007
    The comment has been removed

  • Anonymous
    May 16, 2007
    Keith, thank you for the great insight into how OrchestrationEventStream works. I have a quick question about using it: my expression shapes that deal with BAM activities do it by calling methods that are in other assemblies, and I'm not sure how scoping rules apply with OrchestrationEventStream (i.e. Is the method in the external assembly "part of" the executing orchestration?). Am I able to call OrchestrationEventStream.DoSomething() from the method in that other assembly and I will get the desired behavior of OrchestrationEventStream? Additionally, will I only need to reference Microsoft.BizTalk.Bam.XLANGs in the called assembly or will I need to reference it in the assembly that contains the orchestration as well? Thanks, Nick

  • Anonymous
    May 16, 2007
    Nick, On your first question, I see no reason why it won't work. I believe there was another client that tried this out.  I haven't had time to try this out myself.  Would greatly appreciate if you try it out and share the result. If not I will post a result perhaps earlier next week.

  • Anonymous
    May 21, 2007
    Hi Keith, Sorry I didn't get to this sooner. I tried calling OrchestrationEventStream methods from an external assembly and all seems to work fine. I've only done a tiny bit of ad-hoc testing, so I can't confirm that the behavior is exactly what is expected in terms of transactional processing, but everything gets populated to the tables. Not entirely sure how it gets the executing orchestration instance through reflection since nothing about the orchestration is passed directly to my method - I imagine it's through reflection or just calling context. To answer my own questions from last week, yes, calling OrchestrationEventStream methods from an external assembly works, and you only need to reference Microsoft.BizTalk.Bam.XLANGS in the assembly that is calling those methods (as opposed to having to reference it in the orchestration assembly too). Nick

  • Anonymous
    May 21, 2007
    Hi Nick, You are right on both :)  Under the cover it is using CallContext class, if a specific tracking data object is not found, nothing will be done. So, if you happen to share this code somewhere else that is not in Orchestration context, nothing will happen. Thanks, Keith

  • Anonymous
    June 28, 2007
    Many of you guys are eagerly anticipating the release of the Microsoft BizTalk Server 2006 R2… and the

  • Anonymous
    June 09, 2009
    PingBack from http://menopausereliefsite.info/story.php?id=33