BizTalk provides two types of property promotions: Distinguished Fields and Property Fields.
In a simplified manner, distinguished fields can only be used within orchestration whereas promoted property fields can be accessed through all phases of the BizTalk message processing, either in orchestrations or from custom code, routing, and pipelines
| Distinguished Fields | Promoted Properties (Property Fields) |
| Are only accessed within an orchestration, and they are not available to other BizTalk Server objects, such as receive locations, send ports, send port groups, and tracking utilities. | Accessed through all phases of the BizTalk message processing, either in orchestrations or custom code, routing (receive and send ports) and pipelines. |
| Do not participate in routing IsPromoted = false | Used for routing (subscription mechanism) IsPromoted = true |
| Not used for tracking | Used for tracking |
| They are not persisted to the MessageBox database. Instead, they are essentially XPath aliases, which simply point to the appropriate XML data field. | Are persisted to the Message box database. |
| Do not have a size limitation | A maximum 256-character length limitation |
| Accessed through a reference to the name of the message, the name of the record structure containing the distinguished field, and the name of the distinguished field, with each named item separated by periods:
MessageName.RecordName.FieldName | Accessed through a reference to the name of the message, the name of the property schema, and a name of the promoted property, via the following format:
MessageName( |
| Do not require the creation of a corresponding property schema | Require the creation of a corresponding property schema |
| Cannot be used to promote values in a record | Can only be used on records with Simple Content type |
| Both can be used to promote elements and attributes | |
| Cost less | Have the additional overhead of being written in both to the Message Box context tables and the subscription tables |
Notes:
- In short, use distinguished fields unless you have to access the field when routing the message. And use it frugally to incur fewer performance penalties.
- Certain scenarios will call for sensitive information, such as a bank account number, to be used as a promoted property. To allow for enhanced troubleshooting and detailed reporting, promoted properties can be viewed in tools such as Health and Activity Tracking (HAT) and Business Activity Monitor (BAM). Based on privacy regulations, these data fields may need to be hidden from these tools, which can be accomplished by setting the promoted property’s Sensitive Information property to True (this configuration is applied on the property schema).
What are Promoted Properties and How to promote properties?
Promoted Properties are Message Context Properties that are flagged as promoted.
Being promoted it allows the Message Engine to route messages based on their value, and being in the message context allows doing so without having to look at the message payload (which would be an expensive operation).
They are the most common way to enable content-based routing.
There are 2 ways to promote a message element:
- Quick promotion: Quick promotion is the simplest way to create a promoted property. Simply right-click on the element’s node and choose Quick Promotion. When choosing this option, Visual Studio will create a property schema called “PropertySchema.xsd” and add in the message’s schema a reference to the generated property schema.
- Manual Promotion: To manually promote a property, a property schema must be created with the elements that will hold the promoted property values. To create a property schema, you need to add a new item in your BizTalk solution, and chose Property Schema as the type of file. Once all the elements are created in the property schema, you associate the property schema with the message’s schema
What are distinguished fields and how to create a distinguished field?
Distinguished fields are message elements that are written into the message context.
The main source of confusion between distinguished fields and promoted properties is that they are both created in Visual Studio’s Schema Editor through the “Promote -> Show Promotions” contextual menu option of a message schema’s element.
Once the dialog box is open, make sure that you are on the Distinguished Field tab, select the message elements and click the “Add>>” and “<<Remove” buttons to add and remove distinguished fields.
It’s a very useful article. Thank you
Good one!!
One more good article. Thanks for posting, Sandro!
I’d add also:
* promoted properties can be used in correlation sets.
* both: promoted and distinguished property node should be exactly one in the Xml document, i.e.the node should have MinOccur = 1 and MaxOccur = 1. If the node missed in the Xml document, we got the run-time error. For distinguished property we have choice, we can use xpath to pass this limitation. But for promoted property node must be exactly one.
* To check the existence of the promoted property inside orchestration we can use the Expression shape with construction like this:
if (myProperty exists myMessage) { …; }
It is not possible to use this expression in the Message Assignment shape because using the “if” statement inside Message Assignment is prohibited.
* If you want to enumerate all promoted properties in current environment, you can use this API [http://code.msdn.microsoft.com/BizTalk-Custom-API-abacd760].
Awesome additional information. Thank you Leonid.
Valuable information sir.
What happens if i make a field both distinguish and promoted.
Hi Sandro, great article. Is there any way to change the target folder for the Default Property Schema so that the auto-generated quick promotion property schema is generated in a specific place? I’ve tried putting a solution filepath into the schemas Default Property field, but it seemingly refuses certain filepaths.
I never try but I don’t think so. Nevertheless, after is created I think you can move it to another folder without any problem (but never try that also)