none
Distinguished Fields VS Promoted Property. RRS feed

  • Question

  • Hello,

    I am a newbie in BizTalk server. I have started reading a book "Microsoft BizTalk Server 2010 Unleashed". I have read about difference between Distinguished field and Promoted Property. 

    "Distinguished fields are the only ones of the two that can be used to write values into content of a message. Changing the value of a promoted property changes only the value in the context. Demotion can help you get the value into content."

    I understood : I can modify  value of the incoming message by distinguished field in the orchestration. However, I cannot by promoted field(As said, change value in the context.)

    Last week, I have used promoted property and modify the incoming message value. So, I am confused about above statement  "Changing the value of a promoted property changes only the value in the context".

    Please suggest.


    Thanks, Mohit Dahiya

    Monday, August 8, 2016 4:52 AM

Answers

  • Hi Mohit

    Any message that is published to BizTalk has two components - 1) one/more message parts(body) and 2) a context(which is a collection of property names and their values).

    Now, a Distinguished field is a shortcut/xpath to a given element/field in the message body. So if you set a value on a distinguished field in orchestration, it is actually changing the message content for that particular field in the message body.

    On the other hand, if you change/set the value of a promoted property, it affects the context property collection, by changing/setting one of the context property values in the collection - it does not change the message content.

    Note:

    Both of the above operations have to be performed in a Construct Message Shape, and you cannot set distinguished fields/promoted properties on a message that you have received in the orchestration. You always have to create a copy of the received message, and perform the changes in a Construct Message Shape.

    Please refer below links for more details on this-

    https://sandroaspbiztalkblog.wordpress.com/2009/03/28/distinguished-fields-vs-promoted-properties/

    https://sandroaspbiztalkblog.wordpress.com/2009/10/26/biztalk-training-accessing-and-change-message-values-inside-orchestration/

    https://blog.tallan.com/2006/12/20/distinguished-fields-vs-property-fields/


    Thanks Arindam





    Monday, August 8, 2016 5:01 AM
    Moderator
  • Hi Mohit,

    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.

    Behind the scene, the real difference lies within the implementation of these two types of promotions. For promoted property fields, BizTalk simply takes note of the XPath expression used to point to the property fields, whereas for distinguished field, the values of the fields are actually copied to the message context within the orchestration.

    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.

    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.

     

    Refer: https://sandroaspbiztalkblog.wordpress.com/2009/03/28/distinguished-fields-vs-promoted-properties/


    Rachit Sikroria (Microsoft Azure MVP)

    • Proposed as answer by - Anand - Tuesday, August 9, 2016 9:46 AM
    • Marked as answer by Mohit Kumar Dahiya Tuesday, August 9, 2016 10:09 AM
    Monday, August 8, 2016 6:26 AM
    Moderator

All replies

  • Hi Mohit

    Any message that is published to BizTalk has two components - 1) one/more message parts(body) and 2) a context(which is a collection of property names and their values).

    Now, a Distinguished field is a shortcut/xpath to a given element/field in the message body. So if you set a value on a distinguished field in orchestration, it is actually changing the message content for that particular field in the message body.

    On the other hand, if you change/set the value of a promoted property, it affects the context property collection, by changing/setting one of the context property values in the collection - it does not change the message content.

    Note:

    Both of the above operations have to be performed in a Construct Message Shape, and you cannot set distinguished fields/promoted properties on a message that you have received in the orchestration. You always have to create a copy of the received message, and perform the changes in a Construct Message Shape.

    Please refer below links for more details on this-

    https://sandroaspbiztalkblog.wordpress.com/2009/03/28/distinguished-fields-vs-promoted-properties/

    https://sandroaspbiztalkblog.wordpress.com/2009/10/26/biztalk-training-accessing-and-change-message-values-inside-orchestration/

    https://blog.tallan.com/2006/12/20/distinguished-fields-vs-property-fields/


    Thanks Arindam





    Monday, August 8, 2016 5:01 AM
    Moderator
  • Thank you Roy.

    Agreed, Distinguished field change the message content and Promoted property change the message context property.

    When we use Construct message, we create a new message. Due to this, I was able to modify the message field value by promoted property(as I am creating a new message). 

    Conclusion : We cannot change the incoming message in BizTalk message box. However, we can create a copy of message and modify the message(Use Distinguished field, Promoted property and XPath). 

    Am I right Roy?


    Thanks, Mohit Dahiya

    Monday, August 8, 2016 5:31 AM
  • When we use Construct message, we create a new message. Due to this, I was able to modify the message field value by promoted property(as I am creating a new message). 

    Hi Mohit

    If you are setting a property schema field(based on a message element) in orchestration on a new message, you will be able to change the actual message field value due to the way orchestration demotes these property values in the message body before publishing it to the message box. It is a special case/handling within orchestration.

    The same will not happen if you write/promote a property schema field from a pipeline component.


    Thanks Arindam





    Monday, August 8, 2016 5:37 AM
    Moderator
  • Hi Mohit,

    First of all you need to understand the difference between the content and context in reference to the BizTalk terminologies.

    Content of Message: Content of the message is the part of the message which actual contains the data relataed to a processes e.g. EmployeeName, id etc.

    Context of Message: Context of the message is the part of message which is used by BizTalk to actually process and correlate the messages out of many task, the context of the message may contain the Stock BizTalk context properties which are used by BizTalk to process the Message inside the BizTalk Engine.

    Now difference between the Promoted property and Distinguished fields??

    Distinguished fields is just an easy way provided by BizTalk to developer to assign or read from the message content(i.e part which actually contains the information xml) using xpath, which in normal case of C# development you have to provide to write to or read from an xml document. Thus your distinguished field value can not be used out of the orchestration as it is not loaded into memory specifically, it is just reading of value from message Content using the xpath. Distinguished field though has some limitations, it cannot be used when the node you select to be a distinguished appears multiple times in the message content.

    Promoted Property: BizTalk has a list of stock properties which it has defined in a Property schema. These properties are used by BizTalk to do the internal processing. In case you want to promote a property, you add a property schema to your VS solution and add the nodes to this property schema representing the properties that you want to promote and set them as MessageContextProperty

    Now when BizTalk encounters a statement like

    pInMsg.Context.Write("PropertyName","Namespace of the Property Schema","Value");

    pInMsg.Context.Promote("PropertyName","Namespace of the Property Schema","Value");

    This writes and promotes the value to the message context part and it is loaded into the memory hence it is available outside of orchestration and can be used any where.

    Regards,


    Mandar Dharmadhikari

    Monday, August 8, 2016 5:50 AM
    Moderator
  • Hi Mohit,

    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.

    Behind the scene, the real difference lies within the implementation of these two types of promotions. For promoted property fields, BizTalk simply takes note of the XPath expression used to point to the property fields, whereas for distinguished field, the values of the fields are actually copied to the message context within the orchestration.

    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.

    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.

     

    Refer: https://sandroaspbiztalkblog.wordpress.com/2009/03/28/distinguished-fields-vs-promoted-properties/


    Rachit Sikroria (Microsoft Azure MVP)

    • Proposed as answer by - Anand - Tuesday, August 9, 2016 9:46 AM
    • Marked as answer by Mohit Kumar Dahiya Tuesday, August 9, 2016 10:09 AM
    Monday, August 8, 2016 6:26 AM
    Moderator
  • Thank you all for the reply.

    @Roy.. I have created a simple application which contain a orchestration, a Empschema and a Property schema. 

    Input schema contains 40 value of the EmpID. I am modifying value of the EmpID in the orchestration.

    msgOutput(BizTalk_Server_Project3.PropertySchema.EmpID) = "16";

    As suggested you, If I check body parts and context property, both have new values.

    Please suggest.


    Thanks, Mohit Dahiya

    Tuesday, August 9, 2016 7:16 AM
  • Hi Mohit,

    msgOutput(BizTalk_Server_Project3.PropertySchema.EmpID) = "16";

    will write the value 16 to the message context for the property EmpId.

    Other than that are you doing any message assignment in the orchestration or some transformation???

    above statement that you have used in your orchestration will only write a property to the message context but will not change the value of EmpID in message content. There is something else that is overwriting the value in Message body.

    regards,


    Mandar Dharmadhikari


    Tuesday, August 9, 2016 7:48 AM
    Moderator
  • Hi Mohit

    What you are seeing is the correct behavior. What is happening is that the orchestration is demoting this context property field to the message body before publishing it to the MessageBox. This is a special handling done within orchestrations. This is applicable for property schema fields that are based on message elements, like in your case.

    If you had written the property field in a custom pipeline component, you would not observe this behaviour. 

    Also note that the property that you are writing in Expression shape is not promoted, it is just written to the context. To promote from orchestration, you have to create/set a CorrelationSet.

    Note: I have edited my earlier post as well to avoid confusion.


    Thanks Arindam



    Tuesday, August 9, 2016 8:30 AM
    Moderator
  • Thank you Mandar for the reply.

    No, I am not doing any other message assignment.


    Thanks, Mohit Dahiya

    Tuesday, August 9, 2016 10:03 AM
  • Thank you Roy.

    As suggested you, I have created a custom pipeline component and got the difference. Thanks once again.


    Thanks, Mohit Dahiya

    Tuesday, August 9, 2016 10:05 AM