BizTalk Training – Accessing and change message values inside orchestration

There are 3 ways that we can read and set values of the message inside orchestration:

  • Using Property promotion
  • Using XPath expressions
  • Using C#/VB.NET object (serialization)

The last one is the most uncommon, but it can be done by serializing the message into an object.

Using Property promotion

Property promotion is about getting easy and fast access to data.

  • Easy: Because you typically do not have to know anything about your data to get access to it. Rather than some long XPath query with possible errors.
  • Fast: Because you do not have to load the whole message into memory to get access to the data. It is placed inside the message context (a collection of key-value pairs that are associated with a message).

BizTalk provides two different types of promoted properties based on what you want to do with the data. The two types are:

  • Promoted Properties are system-wide.
  • Distinguished Fields are lightweight and only accessible inside an Orchestration.

They are read/write, so they provide an easy way to change values inside your message without using a map, such as updating a status field.

Learn more: Distinguished Fields vs. Promoted Properties, Basics of Promoted Properties

Property promotion: Quick Promotion

Using Promoted Properties:

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName)), System.Diagnostics.EventLogEntryType.Error);
//SET (Write)
msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName) = "Sandro";

Using Distinguished Fields:

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput2.LastName), System.Diagnostics.EventLogEntryType.Error);
//SET (Write)
msgOutput2.LastName = "Pereira";

Using XPath expressions

Working with XPath inside Orchestrations is a powerful and simple feature of BizTalk. XPath can be used to both read values and set values inside your Message. To set values in your message, you need to be inside a Message Construct shape.

XPath queries can only be done against a Message – can also be executed against untyped messages (that is, a Message that is of type System.Xml.XmlDocument) – and the results can be set to a Message, XML Document or other orchestration variables.

Learn more: XPath 1.0 Function Library Quick Reference, Operators and Special Characters Quick Reference

To see what is the XPath expression of the field:

  • Go to the schema and select the field that you want
  • Right-click and select “Properties
  • Select the value of the property “Instance XPath
Message Element instance XPath

Using XPath Expression in Message Assign:

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(xpath(msgOutput3,"string(/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()=''])")), System.Diagnostics.EventLogEntryType.Error);
//SET (Write)
xpath(msgOutput3,"/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()='']") = "00";

Using C#/VB.NET object (serialization)

BizTalk able to automatically convert the message into a C# object and C# object into BizTalk message.

To accomplish this, we have to generate C#/VB.NET classes based on Schemas using XSD.EXE, or those of you not familiar with XSD.EXE it’s a command-line tool shipped with Visual Studio .NET that allows you to generate Classes or Typed DataSets based on XML Schemas, normally you might try to write code to create an XML Document (based on a schema), you end up writing pages and pages of painful code to construct an XML document by using the DOM (XmlDocument).

How to create a class from schema:

  • Start Menu -> All Programs -> Microsoft Visual Studio … -> Visual Studio Tools -> Visual Studio … Command Prompt
  • Go to the Schema folder and type “xsd /classes /language:CS Schema1.xsd

Create Orchestration variable

  • First, you have to create an orchestration variable from the class that you create previously
  • On property Type select <.NET Class…> and select Person class that you created previously
Variable inside Orchestration

Using C# object inside Message Assign:

varPersonMsg = msgInput;
System.Diagnostics.EventLog.WriteEntry("Orchestration", varPersonMsg.FirstName + " " + varPersonMsg.LastName, System.Diagnostics.EventLogEntryType.Error);
//SET (Write)
varPersonMsg.FirstName = "Sandro";
varPersonMsg.LastName = "Pereira";
varPersonMsg.Age = "00";
msgOutput4 = varPersonMsg;

Source Code/Download


You can download the source code from GitHub here:

Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can help us buy a Star Wars Lego for my son! 

#1 all-in-one platform for Microsoft BizTalk Server management and monitoring
Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

7 thoughts on “BizTalk Training – Accessing and change message values inside orchestration”

  1. Hi i m getting error saying Identifier firstname doesnt exist in varPersonMsg are you missing assmebly refernce.. I m using multipart message

Leave a Reply

Your email address will not be published. Required fields are marked *


Back to Top