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 componen
- Promote the Create a Correclation Se
- 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 |
| Create a map to transform the SalesOrder to an OrderEvent message |
| 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 |
| Set the ESB properties on the message with the custom .NET component |
| Create a Correlation Set so that context properties on the message are also promoted. |
| Use the Correlation Set in the Send Shape when sending the OrderEvent message to the MessageBox |
| 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. |
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 simple Receive Port in the 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. |
| The Itinerary picks up the event message and writes it to an output folder. |
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 Solution with the .XSD schemas, Map, Orchestration, Custom Component and Itinerary here:
Note
The sample is in BizTalk 2013 but this is also possible in BizTalk 2010