How to promote the BizTalk Server Receive Location Name property

As you most likely are aware, when a document is received by a BizTalk Server adapter, the adapter creates a BizTalk message for the document. The BizTalk message contains the document that was received as well as the message context. The message context is a container for various properties that are used by BizTalk Server when processing the document. Each property in the Message Context is composed of three things, a name, a namespace, and a value.

Message context properties are added to the message context throughout the lifetime of the message as it passes through the BizTalk Server. These properties:

• Are either extracted from the message itself, for example, order id or shipment number
• Or added by pipelines and adapters at the receive location, for example, transport name or receive port name

There are mainly two benefits of this context:

• The first is to provide the various components of BizTalk, and easy access to these properties, without having to parse the message
• The second is to support content-based routing.

However, there are several out-of-the-box BizTalk Server context properties that are not exposed (promoted) and by that, they are not available for routing in BizTalk Server. This behavior is common to all versions of BizTalk Server, not to a specific one. You can know more about all out-of-the-box BizTalk Server context properties on this extended whitepaper: 

• Your Guide to BizTalk Message Context Properties

Nevertheless, BizTalk Server allows you to extend these out-of-the-box capabilities by adding new custom property schemas to your solutions. Once after deployment, these custom context properties can be used in all components, inside Orchestrations, pipelines, or ports.

One such property is the ReceiveLocationName property. While ReceiveLocationName is available on the http://schemas.microsoft.com/BizTalk/2003/system-properties namespace and we can see it in the Context of the message inside the BizTalk Server:

The ReceiveLocationName property is not promoted in the BTS namespace, only the ReceivePortName property is available. Therefore, we cannot access it inside an Orchestration or add a filter in a send port using the BTS.ReceiveLocationName syntax.

Nonetheless, we can access this information for example using a custom pipeline component inside a receive pipeline by using this command: 

string receiveLocationName = 

pInMsg.Context.Read("ReceiveLocationName", "http://schemas.microsoft.com/BizTalk/2003/system-properties");

To bypass this behaviour, and as I mentioned above, BizTalk Server allows you to create custom property schemas and extend the out-of-the-box promotions with more fields. So for us to easily promote the ReceiveLocationName property we need to create a custom Property Schema.

Add a custom Property Schema

As far as BizTalk Server message properties go, they can be assigned Property Schema Base types of:

• MessageDataPropertyBase (default) – This type means that the XPath to the property value in the message must exist.
• MessageContextPropertyBase – opposite to the previous, this type means that the XPath may or may not exist.

Taking this information into account, what we now need to do is:

• Open a new or existing BizTalk Server Visual Studio solution and then create a property schema,  by right-clicking on the project name and selecting Add > New Item…

• From the Add New Item window, select BizTalk Project Items and then Property Schema, and provide a name, for example, schExtendBTSProperties.xsd and click Add.

• To simply be able to access the fields on orchestration or filters in send ports, we can go ahead and change the Namespace of the .NET schema type to “ExtendBTS”.
  • This is just a shortened namespace similar to the “BTS” namespace in Microsoft.BizTalk.GlobalPropertySchemas assembly.
  • Note that this is not the Target Namespace, instead select the schema and go to its properties and you will find the Namespace property

• We can rename or delete the Property1 field, but what we will need in our case, is to add a property called: ReceiveLocationName.

Note: A MessageContextPropertyBase property means that the XPath may or may not exist. 

• Compile the project and deploy it. 

Now that we have the schema, we just need to create a Custom Pipeline component and a custom receive pipeline to promote this property to the context of the message

Create a custom Pipeline Component and custom receive Pipeline

To actually promote the properties to the context of the message, we need to create a custom pipeline component and a custom receive pipeline to do the trick.

The custom pipeline is quite simple, we just need two lines of code:

string rlocationname = (string)pInMsg.Context.Read("ReceiveLocationName",
 "http://schemas.microsoft.com/BizTalk/2003/system-properties");

The above line reads the receive location name that was executed in runtime. And this line below will promote the value to the field we create earlier:

pInMsg.Context.Promote("ReceiveLocationName", "<target-namespace-schema-created-above>", rlocationname);

On the pipeline, we just need to drag the component we create for example to the Decode component:

You can find a sample of the custom component and pipeline here:

• Receive Location Name Property Promotion Pipeline Component