BizTalk Property Promotion

Property Promotion:

Property Promotion in BizTalk is usually about taking values from incoming message and moving them into the context of the message, so they are easily accessible and usable for routing. The context of message is a set of metadata about a message that resides in the message box with the message, allowing different part of BizTalk to read in a small set of metadata instead of the entire message, in case a value from a message needed at run time.

Below are three options for Property Promotion:

  • Distinguished Field
  • Property Schema
  • XPath

Note: Only those fields can be promoted as distinguished field or Property schema which occur only once in the message.

Following error will happen when promoting a value that can occur multiple times



XPath is much slower than Promoted Property and Distinguished Field. XPath function requires the Orchestration Engine to load the entire message into the memory to evaluate the XPath expression.

XPath should only use for getting and setting value of element that are recurring where Promoted Property and Distinguished field can not helpful.

Use of Property Promotion in Orchestration:

Distinguish Field:

Variable = MessageName.RecordName.FieldName;

Property Schema:

Variable = MessageName(PropertySchemaName.PromotedPropertyName);


Variable = xpath(MessageName, XPath of the xml element);

e.g. variable = xpath(MsgReceive,”/*[local-name()=’EmpDetails’ and namespace-uri()=’http://BizTalkTutorial.Blog.Test.Schemas.Source’%5D/*[local-name()=’Name’ and namespace-uri()=”]”)

you can get XPath from Instance XPath from Schema properties as below:

Difference between Distinguished Fields & Property Schema

Distinguished FieldsProperty Schema
These field are excellent and fast way to both accessing and writing values to and from in OrchestrationOnly Promoted Property can have used for message routing, correlations and can be used in orchestrations
These fields are restricted to contains values that comes from some element (that can occur only once)It can contain data that is purely metadata about the message
Do not participate in routing
IsPromoted = false
Only promoted property can be used for tracking purposes with the build-in tracking functionality
Do not have a size limitationThey are restricted to 256 characters
Do not require the creation of a corresponding property schemaCreate a separately maintained property schema
They are not persisted to the Message Box database. Instead, they are essentially XPath aliases, which simply point to the appropriate XML data field.Promoted properties are persisted to the Message box database. The Message box generate a large join in SQL Server each time a message is published, which is basically a join between the Context of Message, the possible properties, and the properties of all subscribers. So the no. of Promoted Properties should be keep minimum
Use in Orchestration as below: MessageName.RecordName.FieldNameUse in Orchestration as below: MessageName(
Distinguished field through the BizTalk API: pInMsg.Context.Write(“theDistinguishedProperty”,
Promote properties through the BizTalk API: message.Context.Promote(“MessageType”, “”, messageType);
BizTalk Server Monitoring

Leave a Reply

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

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

Facebook photo

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

Connecting to %s

Blog at

%d bloggers like this: