So You Want To Write An Orchestration?

  • Article

Is there a BizTalk Server 2006 orchestration in your future? This post is a modest attempt to catalog some of the many useful tidbits of information out on the web. It will evolve over time.

  • Legend
    • blog = blog post
    • core = BizTalk Server 2006 core documentation hosted on MSDN.
    • lib = non-core docs at Microsoft
    • other = general resource out on the vast interweb
    • wp = BizTalk Server 2006 whitepaper

Still not sure about the legend but since I used one for the map content, I'll use it here. And now for the material:

  • For the Newby
    • About Orchestrations (core) - basic overview topic describing what an orchestration is along with its basic components. It includes many relevant child topics, some of which are called out below; others are less important but worth a look for the newby.
    • The Orchestration Design Surface (core) - a quick shake-down of the orchestration development UI. Nice to see all of the features so you know they are there if you need them.
    • Steps in Orchestration Development (core) - add shapes, define schemas, define ports, bind Send and Receive shapes to ports, assign or transform data between messages, identify custom components, use orchestration variables to manage data, build and test. Oh, pay attention to the note: "If the Copy Local property of the referenced assembly is set to True, Orchestration will not be able to pick up any changes made to the external assembly after the initial add reference takes place in BizTalk project." Learn it. Know it. Live it.
    • Creating Orchestrations (core) - is a parent containing many relevant topics, from working with the orchestration designer and designing orchestration flow to using correlation, role links, ports, maps, business rules, web services and transactions / exceptions. Newbys should at least skim all of the material to get a good sense of the mechanics of designing an orchestration.
    • How To Build an Orchestration (core) - with related information on handling Build Errors in the Task list. Building is pretty simple; understanding and resolving errors can be difficult for the newby. One of the more common errors is "Compiler asks if you are missing an assembly reference" -- it can ask, but you don't have to tell it. Advice is given in the topic. For those who want a peek, one potential solution is to add a reference to the missing assemblies your project requires.
    • Security Considerations for Developing Orchestrations (core) - contains one note, "avoid subscriptions from untrusted messages". This will ensure that low-privilege messages do not initiate an orchestration instance that could potentially create subscriptions based on the message content or context.
    • Orchestration Dehydration and Rehydration (core) - parent topic defines dehydration and rehydration; child topics go into the details. Knowing what the engine does is critical to designing performant orchestrations.
    • Debugging Orchestration Runtime Errors (core) - explores different problems and their solutions in a question/answer format. For example, "Why do I get errors when I attach a dynamic send port to a logical port?"  Answer: a dynamic port gets an address only; it does not inherit the other information associated with the logical port.
    • Debugging tactics including Writing Information to the Event Log, Debugging Orchestrations by using Custom Code, and Configuring Remote Debugging for Orchestrations (all in the core docs). You may need to employ one, two or all of these methods (and others) during your BizTalk Server career so its best to learn them early.
    • Tracking Orchestrations with HAT (core) - describes where you can set breakpoints and what information is available. Child topics discuss interactive debugging and working with the orchestration debugger. Reading about it and actually doing it are two different experiences -- try it out for yourself using one of the orchestration samples in the SDK.
    • Managing Orchestrations (core) - contains topics that describe how to manage your orchestration once it has been deployed. Typical tasks include working with bindings, enlisting/unenlisting, stop/start/suspend/resume and other operations. Review this before you begin development so you have an idea of the kind of deployment and configuration tasks your solution will need.
    • FAQ For BizTalk Orchestrations (wp) - features a collection of frequently asked questions about orchestrations. This is aimed at all audience levels but makes especially great reading for the newby. What better way to discover patterns, what works, what doesn't, pitfalls, and other helpful nuggets prior to writing your first orchestration? Take a look.
  • For Everyone
    • How To Avoid Throttling Correlated Messages (core) - this topic is chock full of throttling advice goodness. A sneak peek: "A lot of developers think about the receive locations for a solution as receiving both activation and correlated messages for the solution through the same port. This is natural as it minimizes the number of addresses that message senders need to keep track of. However, with the addition of throttling in BizTalk Server 2006, there can be advantages to thinking about the stream of activation messages and the stream of correlated messages separately when it comes to throttling." Take a look.
    • Persistence and the Orchestration Engine (core) - discusses persistence points, serialization, system shutdown, and recovery behavior. Points out interesting points about .NET class requirements for serialization (need to be marked Serializable) and COM objects (If you want to call a COM object outside of an atomic transaction, you must wrap the COM object in a .NET object that is .NET serializable and knows how to persist and restore the state of the COM object).
    • Optimizing Resource Usage Through Host Throttling (core) - contains a few useful topics on throttling including What Is Host Throttling, How BizTalk Server Implements Host Throttling, Host Throttling Performance Counters, and How To Avoid Throttling Correlated Messages among others.
    • Measuring Maximum Sustainable Tracking Throughput (core) - as the topic says, once you have deployed a solution you should track and monitor the system to understand how it is performing, what exceptions can occur and why, and the current state of business processes (orchestrations, etc). Describes DTA Tracking and BAM tracking with great overviews and architectural diagrams.
    • Developers Troubleshooting Guide to BizTalk Server 2006 (wp) - a tome containing troubleshooting advice for all aspects of BizTalk Server including orchestrations. Be sure to drop me a line c/o this blog if it is missing info.
    •  
  • Samples
    • HelloWorld (core) - demonstrates how to process XML messages into related, but distinct, types of XML messages by using BizTalk orchestrations and maps.
    • MethodCall (core) - demonstrates how to call a .NET-based method from a BizTalk orchestration.
    • ConsumeWebService (core) - demonstrates how to invoke a Web service from within a BizTalk orchestration.
    • ExposeWebService (core) - demonstrates how to expose a BizTalk orchestration as a Web service.
    • CallOrchestration (core) - demonstrates how to call a BizTalk orchestration from another orchestration.
    • Compensation (core) - demonstrates how to use the Compensate shape in an orchestration.
    • PartyResolution (core) - demonstrates how to use BizTalk orchestrations with party resolution to route instance messages.
    • BPEL Import (core) - demonstrates how to create an orchestration from a Business Process Execution Language (BPEL) description of a process and related artifacts.
    • Publishing and Consuming Web Services with SOAP Headers (lib) - This sample demonstrates how to publish a BizTalk orchestration as a Web service with a SOAP header and how to consume the SOAP header from a Web service request message.
    • Delivery Notification (lib) - a concise example of how acknowledgements work and how to use delivery notification in your orchestration.
    • Using Long-Running Transactions in Orchestrations (lib) - shows how to use long-running transactions in an orchestration. There are two examples: a long-running transaction with time-outs and a long-running transaction with custom compensation.
    • Parallel Convoy (lib) - demonstrates how to design a parallel convoy in the orchestration designer. A parallel convoy is a pattern that concurrently receives correlated messages in two or more branches of a Parallel Actions shape; messages can arrive in any order. The sample accepts invoices and purchase orders and correlates based on PO number.
    • Direct Binding to an Orchestration (lib) - shows how to bind one orchestration to another orchestration. This is in contrast to binding to the message box and using a subscription (filter) on an orchestration receive port to grab messages.
    • Direct Binding to the MessageBox Database in Orchestrations (lib) - uses ports directly bound to the messagebox database along with filters to process messages. This is in contrast to direct binding to an orchestration. It is a good option when you want "status-based" routing; it also makes it easy to add extra processing steps.
    • Using a Custom .NET Type for a Message in Orchestrations (lib) - uses a custom type as a message type in an orchestration. This is useful if you have existing types in your custom code that you want to use as messages in BizTalk Server. The example is obviously contrived, but a fair example of what you need to do.
    • Writing Orchestration Information as XML Using the ExplorerOM API (lib) - not required by a long shot, but interesting stuff if you have any interest in using the API to work with BizTalk Server objects. This example pulls Orchestration information as XML and runs a quick transform to produce an html document that summarizes orchestrations. Fun romp through the ExplorerOM API.
    • Correlating Messages with Orchestration Instances (lib) - demonstrates the concept of message correlation using a purchase invoice. This one does not include documentation.
    • Atomic Transactions with COM+ Serviced Components in Orchestrations (lib) - if you are using COM+ serviced components, this is worth a look. From the doc - "While atomic transactions behave like Microsoft Distributed Transaction Coordinator (DTC) transactions, they are not explicitly DTC transactions by default. You can explicitly make them DTC transactions, provided that any objects being used in the transaction are COM+ objects derived from System.EnterpriseServices.ServicedComponents, and that isolation levels agree between transaction components.". Tempting stuff.
    • Exception Handling in Orchestrations (lib) - a fine primer on how to handle exceptions in orchestrations.
    • Implementing Scatter and Gather Pattern (lib) - the Scatter and Gather pattern enables you to send messages to multiple recipients and processes, and to receive messages back from each recipient and process. This sample shows you how to implement it.
    • Using the SQL Adapter with Atomic Transactions in Orchestrations (lib) - this sample shows how to use the SQL adapter with atomic transactions to keep databases consistent. The SQL Adapter is often clouded in mystery.
    • Using BizTalk Server For Email Alert Bus (blog) - a neat sample by Richard Seroter that uses an orchestration.
    • Recent BizTalk 2006 Bugs... (blog) - Scott Colestock discusses two bugs, one of which is about orchestrations (and deployment). Worth a read. 
  • Videos, etc
    • What's New in BizTalk Server (other) - virtual labs of some of the key features of BizTalk Server 2006. There are also labs for 2004 that include orchestration as well as other content that still applies to the 2006 version.

Do not go gentle into that BizTalk orchestration. Rage, rage against the suspension of a message.

Sorry Dylan.