Most BizTalk Server developers have some idea about what Property Promotion is. In a simple way, we can say that Property Promotion is the process of taking message or system data and putting it into the message context. The tricky part is to know when and how properties get promoted.
Previously in this blog, I explained How to promote the BizTalk Server Receive Location Name property where we created:
This is required to read, in the runtime, the Receive Location’s name that is being used and to promote it to the context of the message.
Recently, I also wrote a whitepaper about BizTalk Message Context Properties. However, there were two missing topics that I didn’t yet address on this subject. One of them will be addressed in this blog today: How can we Promote data from the message payload to the context of the message itself, where we can do content-based routing.
There are two crucial things you need to know:
For the data payload, BizTalk Server provides two types of property promotions: Distinguished Fields and Property Fields. You can promote a property as a Property Field in much the same way as promoting a property as a Distinguished Field. However, in a simplified manner, distinguished fields can only be used within an orchestration, whereas Property Fields fields can be accessed through all phases of the BizTalk message processing, either in orchestrations or from custom code, routing, and pipelines. A Property Fields requires the existence of a Property Schema.
You might choose Property Field promotion over Distinguished Field promotion for the following reasons:
The values you want to promote are shorter than the 255 character limitation that applies to Property Fields.
You need the values that you promote to be accessible outsides of orchestrations, such as within pipelines or ports.
This topic provides step-by-step instructions for promoting properties as Property Fields.
If we want to promote fields as property fields, we must define a property schema first. This property schema specifies an unstructured collection of fields into which you can promote fields from within an instance message defined by a schema associated with your property schema.
To do that, we need to:
If you don’t have a Property Schema as we created above in your solution, the first time we try to promote an element or attribute, it will automatically create that Property Schema for you in your solution.
To promote elements or attributes of the message, you need to:
Now we just need to deploy and create a receive port/location that uses the XMLReceive pipeline.
And that’s it! Now if you go to the tracking of the messages, you will see these two properties promoted to the context:
I mentioned above that you don’t actually need to create the property schema manually. In reality, if you use the Quick Promotion functionality, this will automatically create a Property Schema called PropertySchema.xsd and will also create the properties inside the schema if they already don’t exist. To do that:
Simple as that!
You can download the full sample from GitHub here:
Happy BizTalk coding!