Promoting properties inside BizTalk is quite common task, after all back bone of BizTalk's underlying routing infrastructure Publish-Subscribe is based on property promotion. There are tons of articles published in the web explaining this concept.

Properties get promoted within BizTalk at different places, Example: some of the properties gets promoted by Adapters, Pipelines Components, Messaging Engine etc,etc. In custom pipeline components ,developers can use either IBaseMessageContext.Write to write context properties or IBaseMessageContext.Promote to promote context properties. The basic difference between writing and promoting (aka distinguished and promoted) properties are, properties that are written cannot be used for message routing, whereas properties that are promoted can be used for message routing. (There are quite few other important differences, but they are not relevant for this article).

Orchestration:

The syntax for promoting properties within Orchestration is

Message(PromotedPropertyName) = value;

Example

MSG_OUT_PERSON(HTTP.ContentType) = "text/xml";

this is the only direct option available within an orchestration to promote a property. Properties promoted by this method are written rather than promoted. That means it can't be used for message routing (filter expressions in Send Port, Orchestration etc).

The sample code contains an orchestration named "PromoteProperty.odx" as shown in below figure, it just receives a message, does property promotion inside the message assignment stage and send the message out.

The following two lines are present inside the "Message Assignment" shape:

MSG_OUT_PERSON = MSG_IN_PERSON;
MSG_OUT_PERSON(PropertyPromotionInsideOrchestration.PropertySchema.ID) = "SK007"

If you look at the outgoing message context, it will look like as shown in figure below, and you can see clearly the property is "NOT PROMOTED"

So, how can you promote property within Orchestration for routing:

Orchestration got the concept of Correlation, basically which routes the response messages to the correct running orchestration instance that initiated the request message. Within Orchestration we use Correlation Set and Correlation type to archive this type of instance routing.

Correlation type is nothing but a set of Properties, Example in our case it's "ID" (you can have multiple properties together to form a single correlation type, Example EmployeeId, EmployeeCompany).

Correlation Set is based on Correlation type and its a set of properties with specific values. When we "Initialize a Correlation set" within orchestration, the orchestration instance automatically promotes those properties in Correlation set into the message context.

We can use this mechanism to promote propeties (rather than just writing properties), there is no need to do a follow up of the Correlations sets we initialized, and it NOT going to create unnecessary subscriptions. (In simple terms you create correlation sets, not for correlation but for property promotion.)

The sample code contains an Orchestration called "PromotePropertyUsingDummyCorrelationSet.odx" which is exact replica of our first Orchestration "PromoteProperty.odx", with one addition. I added a Correlation Type, Correlation Set and Initialized the Correlation set in the Send shape as shown in below figures.

Now, if you look at the outgoing message context , it will look like as shown in figure below. Now you can see ID property is PROMOTED. The attached sample clearly explains this concept. Read the Download section for details.

David Hurtado highlighted this trick on his blog. I expanded his trick with proper sample and more explanation, so that it will be helpful to some one in the future. Or atleast to me if in case I can't remember.

Download:

The download contains the complete source code, sample messages, File drop folders and binding file. Follow the steps to setup the sample.

1. Extract "PropertyPromotionInsideOrchestration" solution to "C:\BTSSamples" folder

2. Open it in Visual Studio, Build/Deploy it, it will create a Biztalk Application called "PropertyPromotionInsideOrchestration". Rectify the errors if something pops up.

3. Open Biztalk 2006 Administration console, right-click on the application "PropertyPromotionInsideOrchestration" and import the binding file "binding.xml". (Start the application).

Execution:

1. Drop the message "NoPromotion.xml" into "FileDrop\In" folder, you'll see the output only in "FileDrop\Out" folder.

2. Drop the message "PromotionWillHappen.xml" into "FileDrop\In" folder you'll see the output in both "FileDrop\Out" and "FileDrop\Out.ByID" folder. (Because message is routed via the second send port to this folder by Content based routing.)