Creating a MessageBox On-Ramp in the ESB Toolkit

Article
1/17/2024

Introduction

In an environment where the 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 need 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 need to create custom code that has to be invoked in an orchestration to perform the steps that are normally made inside the pipeline. The objects that are used in the ESB Toolkit are not described on MSDN so Reflector is your best friend to figure out which objects need to be used and how to invoke them

Steps

In the following example is a Sales Order message going to be processed with an Orchestration. In the Orchestration is an event message created that is sent to the MessageBox and picked up by an itinerary. (An itinerary is not bound to a specific message type and can be used to process multiple message types.)

The following steps are necessary to create the example:

Create XSD schemas for the messages in BizTalk
Create a Map to transform the inbound message to a message for the ESB
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 an Orchestration to process the inbound message
- In the Orchestration:
  - Receive the message
  - Use the Map to transform the inbound 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 the ESB message

Create XSD schemas for the messages in BizTalk

Create a XSD schema for the inbound message that is processed by the Orchestration. Also create a schema for the message that is picked up by the itinerary.
The following XSD schemas are needed:

SalesOrder.xsd
OrderEvent.xsd

Figure 1. SalesOrder.XSD schema

Create a Map to transform the inbound message to a message for the ESB

Create a Map for the message that is picked up by the itinerary. In this example is the SalesOrder transformed into an OrderEvent message.

Figure 2. SalesOrder to an OrderEvent Map.

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.


// Lookup itinerary via resolver
ResolverDictionary dictionary = ResolverMgr.Resolve(config);

Serialize it into an Itinerary object and take the first Itinerary Service from the itinerary.


// Serialize itinerary
StringReader reader = new  StringReader(dictionary.Item("Resolver.Itinerary"));
XmlSerializer ser = new  XmlSerializer(typeof(Itinerary), "http://schemas.microsoft.biztalk.practices.esb.com/itinerary");                                                             
 
//Get Itinerary from string
Itinerary it = (Itinerary)ser.Deserialize(reader);   
 
//Get the first service from itinerary
ItineraryServicesService service = it.Services[0].Service;

Set the necessary properties of the itinerary like beginTime and the interchangeId of the message.


//Create ItineraryV1
Microsoft.Practices.ESB.Itinerary.OM.V1.ItineraryV1 itv1 = new  ItineraryV1();
 
itv1.Read(dictionary.Item("Resolver.Itinerary"));
 
if (string.IsNullOrEmpty(itv1.ItineraryData.uuid))
{
    itv1.ItineraryData.uuid = uuid;
}
 
itv1.ItineraryData.beginTime = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ss.fffZ", CultureInfo.InvariantCulture);
itv1.ItineraryData.completeTime = "";
itv1.ItineraryData.servicecount = itv1.ItineraryData.Services.Length;

Write the ServiceName, ServiceType and ServiceState properties of the first Itinerary Service as promoted properties on the XLANGMessage.


//Write properties
msg.SetPropertyValue(typeof(Microsoft.Practices.ESB.Itinerary.Schemas.ServiceName), itineraryStep.ItineraryStep.ServiceName);
msg.SetPropertyValue(typeof(Microsoft.Practices.ESB.Itinerary.Schemas.ServiceType), System.Convert.ToString(itineraryStep.ItineraryStep.ServiceType));
msg.SetPropertyValue(typeof(Microsoft.Practices.ESB.Itinerary.Schemas.ServiceState), itineraryStep.ItineraryStep.State);
msg.SetPropertyValue(typeof(Microsoft.Practices.ESB.Itinerary.Schemas.IsRequestResponse), false);

Write the created Itinerary object as a promoted property on the XLANGMessage.


//Set ItineraryHeader property value in XLANGMessage
itv1.Write(msg);

Figure 3. Custom component to set the context properties that are needed for the ESB Toolkit.

Create an Orchestration to process the inbound message

The following activities should be carried out:

Receive the SalesOrder message.

Figure 4. Receive Shape.

Use the Map to transform the inbound message to the OrderEvent message.

Figure 5. Transform the inbound message to the OrderEvent message.

Set the ESB properties on the message with the Custom .NET Component in the Construct Message Shape.

Figure 6. 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.

Figure 7. Correlation Set for the ESB Toolkit.

Use the Correlation Set in the Send Shape when sending the OrderEvent message to the MessageBox.

Figure 8. Set the Correlation Set in the Send Shape.

Create an itinerary to process the ESB message

The first Itinerary Service in the Itinerary has to be an orchestration and can’t be a Messaging Service since the pipeline components and the message have been in the MessageBox database. The example itinerary is simple and only has a Routing Service that writes the message to an output folder.

Figure 9. Itinerary to process Events.

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.

Figure 10. DebugView

The Itinerary picks up the event message and writes it to an output folder.

Figure 11. OrderEvent message.

Source Code

You can download the example with the complete Visual Studio solution here:

http://code.msdn.microsoft.com/Creating-a-MessageBox-On-7ef401fa

Share via