Distinguished vs. Promoted Properties

With the BizTalk Editor you create properties on the message schemas and you can choose
either distinguished or promoted properties. So what does that mean, and when do I
use versus the other?

Distinguished fields/properties

Commonly used with: Orchestration

Example use case: A decision in orchestration made on some content in the document.
Make that content a distinguished property.


- These properties do not participate in routing

-  There is no restriction on the length of a distinguished field.

- Distinguished fields are not defined in a separate property schema

- Standard pipeline components ignore distinguished fields but custom components can
access them through the “http://schemas.microsoft.com/BizTalk/2003/btsDistinguishedFields” 
namespace using XPath on their name

Promoted Properties

Commonly used with: Routing

Example use case: when a message is published into the message box route all messages
with the name element = "Great Plains" to the Great Plains adapter and into Great


- These are used for publish and subscribe routing in the messagebox

- They are restricted to 256 characters

- Create a separately maintained property schema

- Are more restricted in the XSD types supported than distinguished properties

When do I use which?

In general you should use a distinguish properties as they are more lightweight unless
you are:

- Routing

- Tracking

- Correlating

- Driving built in pipeline component behaviour

which of course could be all the time depending on your scenario :)...

Comments (4)

  1. Yossi says:

    Cool job! Keeping it going 🙂

  2. catcat says:

    It’s very clear. Please go on. ^o^

  3. Sachin Surana says:


    But how to use a distinguished property in orchestration. When i try accessing it using MESSAGEINSTANCE.DISTPROP it says DISTPROP is not a member of MESSAGEINSTANCE.

Skip to main content