Distinguished Fields vs. Promoted Properties

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 FieldsPromoted 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 trackingUsed 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 limitationA 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 schemaRequire the creation of a corresponding property schema
Cannot be used to promote values in a recordCan only be used on records with Simple Content type
Both can be used to promote elements and attributes
Cost lessHave 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 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.
BizTalk Server Schemas Quick Promotion
  • 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
BizTalk Schemas Manual Property Fields Promotion

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.

BizTalk Schemas Show Promotions
BizTalk Schemas Show Promotions
#1 Azure Monitoring Platform
Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

9 thoughts on “Distinguished Fields vs. Promoted Properties”

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

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

    1. 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)

Leave a Reply

Your email address will not be published. Required fields are marked *


Back to Top