Creating a MessageBox On-Ramp for the ESB Toolkit in BizTalk 2013

In an environment where Microsoft BizTalk ESB Toolkit is deployed, a BizTalk receive location responsible for receiving ESB-destined messages is referred to as an "on-ramp." In the receive location you have to use one of the pipelines provided as part of the toolkit, and then correctly configure the components of that pipeline to determine the itinerary and link it to the message. So you can use almost any location outside BizTalk as an on-ramp but what if you want to pick up a message from the MessageBox database and use an itinerary to process that message? You can’t use pipeline components once a message is picked up by BizTalk and is already in the MessageBox. Therefore you have to create custom code that must be invoked in an orchestration to perform the steps that are normally made inside the pipeline. The objects that are used inside the ESB Toolkit are not described on MSDN so Reflector is you best friend to figure out which objects have to be used and how to invoke them.

Steps

In the following example I’m going to process a sales order message in BizTalk with an orchestration. In the orchestration is an event message created that is sent to the MessageBox and picked up by an itinerary. (The same itinerary can be used to process multiple event types.)

The following steps are necessary to make it work:

  • Create a custom component in .NET to set the context properties that are needed for the ESB Toolkit
    • In the custom component:
      • Resolve the itinerary from the Itinerary Store database
      • Determine the first Itinerary Service in the itinerary
      • Write the properties of the Itinerary Service as context properties on the message
      • Attach the itinerary to the message
  • Create a map to transform the SalesOrder to an OrderEvent message
  • Create an Orchestration to process SalesOrder messages
    • In the Orchestration:
      • Receive the SalesOrder message
      • Use the map to transform the SalesOrder to an OrderEvent message
      • Set the ESB properties with the custom component
      • Create a Correlation Set to promote the context properties on the message
      • Send the OrderEvent message to the MessageBox database with a Direct Port
  • Create an itinerary to process Event messages

 

Create a custom component in .NET to set the context properties that are needed for the
ESB Toolkit
Create a class in .NET with a method that receives a XLANGMessage and the name of the itinerary. 
In the method perform the following activities:
- Resolve the itinerary from the Itinerary Store database with the ResolverMgr class.
- Serialize it into an Itinerary object and get the first Itinerary Service from the itinerary.
- Set the necessary properties of the itinerary like beginTime and the interchangeId of the message.
- Write the ServiceName, ServiceType and ServiceState properties of the first Itinerary Service as
   promoted properties on the XLANGMessage.
- Write the created Itinerary object as a promoted propery on the XLANGMessage.
CustomComponent
 
 
Create a map to transform the SalesOrder to an OrderEvent message
MapSalesOrder_to_OrderEvent
 
 
Create an Orchestration to process SalesOrder messages
Create an Orchestration that receives the SalesOrder message, use the map to transform it to an OrderEvent message, set the properties for the ESB Toolkit and send the OrderEvent message to
the MessageBox with a Direct Port.
Orchestration_ProcessSalesOrders
 
Set the ESB properties on the message with the custom .NET component.
SetItinerary
 
Create a Correlation Set so that context properties on the message are also promoted.
CorrelationProperties
 
Use the Correlation Set in the Send Shape when sending the OrderEvent message to the MessageBox.
InitializingCorrelationSets
 
 
Create an itinerary to process Event messages
The first Itinerary Service in the Itinerary must be an orchestration and can’t be a Messaging Service because in fact that are pipeline components. My itinerary is very simple and only has a Routing Service that writes the message to an output folder.
Itinerary_ProcessEvents

 

Testing the sample

Once the schemas, map and orchestration is deployed to BizTalk, the itinerary is deployed to the Itinerary Store database and de custom component is placed in the GAC, the solution is ready to be tested.
Create a Receive Port and a Receive Location with the BizTalk Administration Console and drop a SalesOrder message in it.
I’ve used the Trace class in System.Diagnostics to trace the steps but you can also use another component for it like ETW tracing.

Run DebugView to watch the trace output.
TraceOutput
 
The Itinerary picks up the event message and writes it to an output folder.
OrderEventMessage

 

Conclusion

It took me quite some time to figure out which objects are necessary for the ESB Toolkit and how they work, but as always, once that is done, it is not very difficult to create the code and get it working!

You can download the example with the complete Visual Studio solution here:
http://code.msdn.microsoft.com/Creating-a-MessageBox-On-7ef401fa

Note:
The sample is in BizTalk 2013 but this is also possible in BizTalk 2010.

About the author

Tomasso Groenendijk lives in Netherlands and is a senior integration consultant at Motion10. He has over 15 years’ experience in software development and software design. Tomasso is specialized in application integration with a strong interest in the Windows Azure cloud platform. In 2014, 2015 and 2016 Tomasso was awarded with the Microsoft Azure MVP award. He is an active contributor to the integration community through his work on his blog, MSDN samples, TechNet Wiki and also speaking on events.

 
 
 
MVP profile Tomasso Groenendijk
 
 
Sentinet Product Specialist
 
 
BizTalk360 Product Specialist

Month List