Property Fields and Distinguished Fields - Interview Question of the Week #1 Day 1

What are Promoted Properties (Promoted Fields)?
Promoted Properties are Message Context Properties that are flagged as promoted, Commonly used with Routing scenario. Once you have added a field to a property schema, its value can be accessed in the orchestration with code and in filter expressions.
This is the most common way to enable content-based routing and available to the pipelines, adapters, Message Bus and orchestrations.

Promoted Fields (= Promoted Properties) are PROMOTED in the message context by the receive pipeline when a message is received on a port. It is usually the job of the disassembler pipeline component such as the XML and Flat File disassembler but any custom pipeline component can also do it.

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 limitationmaximum 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.
  • 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
Using Manual Promotion, it is also possible to promote message elements to promoted properties in the system property schemas shipped with BizTalk. To do so, just browse in the References sub-tree when picking the property schema

How to promote properties through the BizTalk API?
Context properties are stored in a property bag, an object which implements the IBaseMessageContext interface. This interface contains 2 methods which take the same parameters (a property name, an XML namespace, and value for the property).
  • The Write() method is used to write the property value into the message context without actually promoting it. It can be used to write distinguished fields or to write transient values. Calling the Write() method is NOT promoting a property, it is writing a property.
  • The Promote() method is used to write the property value into the message context but also flags the property as promoted so that it is available for routing. This is the method that needs to be called to promote a property.
To promote a property through the API, element name and namespace passed as parameter of the Promote() method must be those of the property defined in the property schema. They are most easily accessed by referencing the property schema assembly and using the properties on the class created for the property.

Example of promoting a property through an API call (copied from the BizTalk 2006 MSDN documentation: Processing the Message):

//create an instance of the property to be promoted
SOAP.MethodName methodName = new SOAP.MethodName();

//call the promote method on the context using the property class for name and namespace
pInMsg.Context.Promote(methodName.Name.Name, methodName.Name.Namespace,

As I mentioned before, it is possible to promote properties to the BizTalk system property schema using Manual Promotion in Visual Studio’s Schema Editor for BizTalk. It is possible to achieve the same programmatically and as for other promotion, the name and namespace passed in parameter of the Promote() method is the one of the promoted property in the property schema, the system property schema namespace in this case.

//BizTalk system properties namespace
private const string BTSSystemPropertiesNamespace = “”;

//Promote the MessageType property
string messageType = “http://” + “” + “#” + “Request”;
message.Context.Promote(“MessageType”, BTSSystemPropertiesNamespace, messageType);

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.

How to create a distinguished field through the BizTalk API
Distinguished fields are written into the context using the Write() method on the IBaseMessageContext object. To be recognized as a distinguished field, the namespace of the property must be "". Pipeline components delivered with BizTalk do not use those context properties. It is nevertheless possible to read/write distinguished field in the code of custom pipelines, as for any other context properties.

Example of writing a distinguished field through an API call (taken from the BizTalk 2006 MSDN documentation: Processing the Message).

//write a distinguished field to the context

Would you use another namespace, it will result in writing a plain transient value in the property bag and won’t be recognized as a distinguished field by the orchestration engine.

//Write a transient value to the message context
message.Context.Write(“MyVariable”, “SomeNameSpace”, SomeData);


No comments:

Post a Comment