Instance Message Processing Using Property Promotion

Promoting properties by using the Property Field method requires the creation of a property schema. For more information about creating a property schema, see How to Create Property Schemas. As with all property promotion, you use the Promote Properties dialog box, which is accessible by using the Promote Properties property of the Schema node in message schemas.

Note

You must choose a pipeline that promotes properties in order to access and use the promote properties. For example, if you use the PassthruReceive pipeline, no properties will be promoted; as a result, content-based routing and other functionality will not work as expected.

In the Promote Properties dialog box, make sure the Property Fields tab is selected in the right side of the dialog box. Next, ensure the appropriate property schema is included in the Property Schemas List at the top of the Property Fields tab. If necessary, use the folder button to select the appropriate property schema by using the BizTalk Type Picker dialog box. Next, expand the nodes in the schema tree on the left side of the dialog box to find and select the Field Element node or Field Attribute node that you want to promote as a property field, and then click Add. Finally, use the drop-down list in the Property column of the Property-Fields dictionary table to select a Field Element node in a property schema with which to associate the promoted property. For step-by-step instructions about promoting properties to property fields using the Promote Properties dialog ox, see How to Copy Data to the Message Context as Property Fields.

Note

You can also promote a Record node to a Field Element node in the property schema, but only if the Content Type property of the Record node is set to SimpleContent.

Note

The same property can be promoted multiple times within a schema as long as all of these promotions are performed under different root nodes. This is because the message is validated against a single root node and only properties promoted under that root node are evaluated at run time.

To remove a Field Element node or Field Attribute node from the set of properties being promoted as property fields, select the promoted property in the Property-Fields dictionary table on the Property Fields tab, and then click Remove.

The Node Path column in the Property-Fields dictionary table shows the XPath to the schema node corresponding to the promoted property. You can edit this value directly by using the Edit Instance XPath dialog box. You can open this dialog box by clicking the ellipsis (...) button that appears at the right end of the corresponding cell when you select that cell. Care must be taken when editing XPath values directly because XPaths that cannot be resolved by BizTalk Editor will prevent proper validation operations.

BizTalk Editor also provides a streamlined command for promoting properties using the Property Field mechanism. This command is called Quick Promotion, and it is available using the Promote | Quick Promotion command on the BizTalk and shortcut menus. This command promotes the selected Field node (or Record node) to a property field that is automatically created in the property schema specified by the Default Property Schema Name property in the Property Pages dialog box for the containing schema. For step-by-step instructions about promoting properties to property fields using the Quick Promotion command, see How to Copy Data to the Message Context as Property Fields.

When you promote a property by using the property field mechanism, two XML Schema definition (XSD) language fragments are added to the XSD representation of the message schema. The first XSD fragment is an annotation fragment associated with the schema element that identifies the corresponding property schema, as in the following example:

<xs:annotation>  
    <xs:appinfo>  
        <b:imports>  
            <b:namespace prefix="ns0"  
                uri="http://BizTalk_Server_Project1.PropertySchema1"  
                location=".\propertyschema1.xsd" />  
        </b:imports>  
    </xs:appinfo>  
</xs:annotation>  

The second XSD fragment is an annotation fragment associated with the Root element (regardless of whether it has been renamed) that identifies the Field Element node or Field Attribute node values that have been promoted by using the property field mechanism, as in the following example:

<xs:annotation>  
    <xs:appinfo>  
        <b:properties>  
            <b:property name="ns0:PromProp1"  
                xpath="/*[local-name()='Root' and namespace-  
                 uri()='http://BizTalk_Server_Project1.Schema2']/  
                 *[local-name()='MyRec1']/@*[local-  
                 name()='Field_x0020_1']" />  
            <b:property name="ns0:PromProp2"  
                xpath="/*[local-name()='Root' and namespace-  
                 uri()='http://BizTalk_Server_Project1.Schema2']/  
                 *[local-name()='MyRec1']/*[local-  
                 name()='ProgramManager']/*[local-name()='Name']" />  
        </b:properties>  
    </xs:appinfo>  
</xs:annotation>  

See Also

Ways to Use Message Content to Control Message Processing
How to Copy Data to the Message Context as Property Fields