Team blog of MCS @ Middle East and Africa

This blog is created by Microsoft MEA HQ near shoring team, and it aims to share knowledge with the IT community.With its infrastructure and development sides,It brings to you the proven best practices and real world experiences from Subject Matter Experts
Follow Us On Twitter! Subscribe To Our Blog! Contact Us

BizTalk ESB: Step by Step Walkthrough Creating a Custom Orchestration Service

BizTalk ESB: Step by Step Walkthrough Creating a Custom Orchestration Service

  • Comments 13
  • Likes

Introduction

The BizTalk ESB toolkit is an implementation of an enterprise service bus messaging standard. It allows for separation between message content, processes implementation, and process configuration.
This is using what is called ESB itineraries. An itinerary would define the lifecycle of the message as it goes through the service bus. The itinerary is composed mainly of itinerary services. There are already itinerary services provided with the ESB out of the box, such as the transformation and routing services.
Usually in many situations you would need to provide more business related logic to be executed using BizTalk orchestrations. This is defined as a custom orchestration service.

Step by step guide

To create a custom orchestration extender you should follow the following steps:

Step 1:     Create a new BizTalk project in visual studio. For example let’s call this “ESB.Samples.Itinerary.Extenders”.

Step 2:     Add references to the ESB assemblies needed which are

Microsoft.Practices.ESB.Adapter
Microsoft.Practices.ESB.ExceptionHandling
Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults
Microsoft.Practices.ESB.Itinerary
Microsoft.Practices.ESB.Itinerary.Schemas
Microsoft.Practices.ESB.Resolver
Microsoft.Practices.ESB.Resolver.BRE
Microsoft.Practices.ESB.Transform

All these should be added from the server GAC.

Step 3:     Add a new orchestration to this assembly and call it (for example) ProcessGWMsg.

Step 4:     Add a direct bound receive port to get the message from the message box database
clip_image001

Step 5:     Add a new message with the expected message type you will be processing in this orchestration.

Step 6:     Add a receive shape to this orchestration and choose the message variable you will receive the message in and link that to the direct receive port already created and mark the Activate property of this shape to True.

Step 7:     Open the editor for the filter expression property of this orchestration.
clip_image002

Step 8:     Add a filter expression like the below
clip_image003
The service name should be unique between all your custom orchestrations to make sure there is no multiple-subscription (unless this is needed of course).

Step 9:     Give the assembly a strong name, build it, and deploy the assembly to the GAC using the command
gacutil /I ESB.Samples.Itinerary.Extenders.dll

Step 10:  Using the command
gacutil /l ESB.Samples.Itinerary.Extenders

Step 11:  Mark the strong assembly full name.

Step 12:  Open the ESB.Config file in the path “C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.1

Step 13:  Search for the section itineraryServices and add a new line at the end of this section as below:

<itineraryServiceid="90E44BB1-0952-4EE9-B761-1B07E0EAE974"name="ProcessGWMsg"type="ESB.Samples.Itinerary.Extenders.ProcessGWMsg, ESB.Samples.Itinerary.Extenders, Version=1.0.0.0, Culture=neutral, PublicKeyToken=3ad832a4e0f593b9"scope="Orchestration"  stage="None" />

Where the id actually is a new generated GUID and the ProcessMsg is the name of the orchestration you will be creating later.

Step 14:  Close visual studio and start it over.

Step 15:  Create a new itinerary called for example “MsgProcessingIti”. Now add to this itinerary all the on-ramp, off-ramp, and itinerary services you want to process your messages. But what we will be interested in is how to call the custom orchestration.

Step 16:  Add a new itinerary service
clip_image004

Step 17:  Change the extender to be an orchestration extender
clip_image005

Step 18:  Open the service name property and you will find the ProcessGWMsg orchestration. Select that.
clip_image006

Step 19:  Now add all the needed resolvers for this itinerary service as needed.

Step 20:  Validate, save, and publish the itinerary to the itinerary database.

Step 21:  Now revert back to the orchestration and define new variables to handle itinerary operations as below

Variable Name

Variable Type

Itinerary

Microsoft.Practices.ESB.Itinerary.SerializableItineraryWrapper

resolverDict

Microsoft.Practices.ESB.Resolver.ResolverDictionary

resolvers

Microsoft.Practices.ESB.Itinerary.ResolverCollection

step

Microsoft.Practices.ESB.Itinerary.SerializableItineraryStepWrapper

Step 22:  Define a new correlation type called “ItineraryAdvance” and define it to include the properties

BTS.OutboundTransportLocation,BTS.OutboundTransportType

Microsoft.Practices.ESB.Itinerary.Schemas.IsRequestResponse

Microsoft.Practices.ESB.Itinerary.Schemas.ServiceName

Microsoft.Practices.ESB.Itinerary.Schemas.ServiceState

Microsoft.Practices.ESB.Itinerary.Schemas.ServiceType

clip_image007

Step 23:  Define a new correlation set of the previously created type in the orchestration with the name “ItineraryAdvanceSet
Now the real purpose of this correlation set is to promote the itinerary properties to allow the message to be routed to the next itinerary service step.

Step 24:  Add a new expression shape to initialize the itinerary variables as below.

clip_image008

itinerary=new Microsoft.Practices.ESB.Itinerary.SerializableItineraryWrapper();
step=new Microsoft.Practices.ESB.Itinerary.SerializableItineraryStepWrapper();
 
itinerary.Itinerary=Microsoft.Practices.ESB.Itinerary.ItineraryOMFactory.Create(msgRawIn);
step.ItineraryStep=itinerary.Itinerary.GetItineraryStep(msgRawIn);
resolvers=step.ItineraryStep.ResolverCollection;

 

Step 25:  You can access the resolvers in the current executing itinerary service by first making sure we have resolvers by adding a decide shape as below.

clip_image009

Where the “ResolverValid” condition is as below.

resolvers.MoveNext()

Step 26:  And to get the resolver dictionary

resolverDict=Microsoft.Practices.ESB.Resolver.ResolverMgr.Resolve(msgIn,resolvers.Current);

Step 27:  And to configure a dynamic send port using parameters coming out of the resolver

DynSendGWMsgPort(Microsoft.XLANGs.BaseTypes.Address)=resolverDict.Item("Resolver.TransportLocation");
DynSendGWMsgPort(Microsoft.XLANGs.BaseTypes.TransportType)=resolverDict.Item("Resolver.TransportType");

Step 28:  Finally when you done processing and want to advance the itinerary you create a new message that will pass to the next step and while creating this message add a message assignment shape with the code.

itinerary.Itinerary.Advance(msgOut,step.ItineraryStep);
itinerary.Itinerary.Write(msgOut);

clip_image010

Step 29:  And when you are sending this message you send it using a direct port to the message box and initialize the correlation set already added to the orchestration previously.
clip_image012

Step 30:  Now edit the orchestration to process the messages as you need.

 Complete sample can be found here. (Please note that the only thing missing in this sample is the actual itinerary and anything you want to do within the orchestration service).
Comments
  • I'm trying to create a singleton to ensure FIFO

    Correlationsets cannot be Initialised on the send port set for every message in the loop

    do we need this correlation sets ?

  • Hello.. Can you please help me in finding the dll's:

    Microsoft.Practices.ESB.Adapter

    Microsoft.Practices.ESB.ExceptionHandling

    Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults

    Microsoft.Practices.ESB.Itinerary

    Microsoft.Practices.ESB.Itinerary.Schemas

    Microsoft.Practices.ESB.Resolver

    Microsoft.Practices.ESB.Resolver.BRE

    Microsoft.Practices.ESB.Transform

    i could not find it in my system to add it.

  • Hi Sudarsan,

    These are found in the path "C:\Program Files (x86)\Microsoft BizTalk ESB Toolkit 2.1\Bin".

  • Hi Arun

    This correlation set is essential if you want to advance the itinerary. the messages sent by the orchestration service to the ESB bus has to have this correlation set or the ESB will not see these fields to be promoted and hence will not advance the itinerary. if you want what you can do is write a custom class or helper function to promote these fields before you send the message to the message box.

  • Hi everybody

    Someone could help me in the step 23, I couldn't understand it, or where I'll get the source code of the example, thanks!!

  • Hi, I am stuck at step 18, ProcessGWMsg.odx is not desplaying for me in the Itinerary designer. Please help. nazeerdada@gmail.com

  • Hi Nazeer,

    Please make sure you have closed Visual studio and opened it again this is essential to refresh the configuration.

  • Hi DiegoT,

    In this step you create a correlation set and this is corrected now. Thanks.

  • Can you make step 15 more detailed?

    I created an on-ramp with OnRamp.Itenerary  recieve port.   used the "Intinerary Test Client" to submit reqest of message defined in Step 5.    

    Nothing happens.   my orchestration did not get called at all.

    please help to detail the step 15.

    Thanks

  • Can somebody share the source code for this.I did not see the link for downloading source

  • Thanks for your last response. Again, I request your help. In step 25 I dropped a decide object and over “resolverValid” I wrote resolvers.Count > 0 Question 1: which object I should put inside resolverValid? I put an expression and wrote resolvers.movenext(); resolverdict=microsoft…..; dynsendGwmsgport…. Question 2: step 28 must be placed inside decide or not? Question 3: step 29 why has 2 send? Thanks pal

  • Due to the fact that I see many questions on how to do several tasks, I included a sample application with this post to make sure things are more clear. Please if you still have more questions do not hesitate to send them to me.

  • thank you

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment