Promotion in general: allow you to access message data inside your orchestration , but
Property promotion : add the promoted fields in the message context , where it become accessible by Custom Pipeline , and Adapters.
And accessible by the Port Filtering, so you can filter your receive port to receive messages with specific value in the promoted fields.
It is a must to use property promotion when you use correlation, since the correlation logically attach messages to each other(using the promoted fields) .. and this process happen outside the orchestration . where only Message Context parameter can be accessed.
You can promote Records only if the Content Type for them are SimpleContent , and you can only use the Property promotion on them.
the Message Context stored in the BizTalk Databases , so the property schema is more costly than the distinguished promotion .. so do not use it unless you have to.
Property Field values are limited to 255 characters in length.
if you try to access optional promoted field, of data type string .If the field exist in the message no problem , you will simply get it is value. But if the field not exists the distinguished promotion will throw exception!! While the property promotion will simply return empty string.
Distinguished Promotion , it is just alias for the Xpath expression to access the message data . so it has no side effects. It is more readable , and the best way to access message data .. if you need only to access it inside orchestrations
Just remember you cannot promote fields unless they are unique (appear once in the message)
So If the field repeatable or one of it is parents repeatable you cannot promote it !