Distinguished Fields vs. Promoted Properties

Posted: March 28, 2009 in BizTalk
Tags: ,

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 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 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:


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:
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


  • In short, use distinguished fields unless you have to access the field when routing the message. And use it frugally to incur less 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.

Tags: BizTalk | Schemas

  1. Gokhan says:

    It’s a very useful article. Thank you

  2. Anonymous says:

    Good one!!

  3. Leonid Ganeline says:

    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].

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s