Click here to Skip to main content
15,940,430 members
Articles / Programming Languages / C#

Using Dynamic Maps in BizTalk

Rate me:
Please Sign up or sign in to vote.
4.70/5 (10 votes)
21 Mar 20067 min read 122.6K   837   42   14
An article on how to use Dynamic Mapping in BizTalk.

Introduction to Dynamic Maps

If you have used maps in BizTalk, by now, you must know that maps are used to transform an XML message into another format. I do not intend to go into the details about BizTalk maps here, but in essence, a map is a transformation on your existing data to the output format you desire. In this article, I will illustrate an interesting feature called Dynamic Maps in BizTalk. If you are a C++ fan like me, you would be amazed at the power of polymorphism and how a call to a function, say Shape.Draw(), differs with each derived class of Shape like Arc, Square, or Circle. So I don't have to explain why dynamic mapping is important.

Quite often in BizTalk, you come across scenarios where you need to transform a message to an output format, which you can decide only after you know some information which is contained in the message itself, like destination recipient. This can be achieved by using maps in the ports itself, but as the number of parties grow and your exception handling requirements kick in, this route has some limitations. This is where dynamic mapping inside orchestrations make sense.


For this exercise, I am building an orchestration which identifies the destination party and loads the corresponding map and sends the message to the intended recipient after the desired transformation. For this example, I have two parties ABC and XYZ.

A Bird's Eye View of the Steps

These are the steps for implementing our Dynamic Maps. I am assuming a working knowledge of BizTalk for the solution below, as the concept is what I intend to illustrate. You can skip these steps by downloading the source from above.

  • Create a BizTalk Project for Maps.
  • Create all Schemas and Maps.
  • Create an Orchestration Project.
  • Identify the party and load the Maps dynamically.
  • Set the Destination dynamically and route the message.
  • Deploy and GAC the DLL.
  • Testing.

Getting Down to Business ..

I have broken down the process into a series of logical steps.

Step 1: Creating your Schemas and Maps Project

You need to create a Schema and Maps project. I have all my maps and schemas in a project called Dynamic Maps. I have added three schemas to the project.

  • The Generic Schema (Common Input Schema)
  • ABC Schema (for my party ABC)
  • XYZ Schema (for my party XYZ)

The details of the three schemas are as below. The input schema comes in with some basic information. The output schemas differ for the two parties ABC and XYZ. The three schemas are shown below.

Image 1

Image 2

Image 3

Right click on SubscriberInfo in the GenericSchema and do a Quick promotion. This will add a property schema to the BizTalk project.

Now we build the two maps. Both the maps use some basic information from the sources schema, and add some additional information on the output side. I have used the Time functoid to get the submission time.

Image 4

Image 5

Step 2: Signing the DLL with a Key

You need to have a strong name for this assembly to get it loaded in the toolbox. So create a strong name and sign it. Once you have the strong key generated, reference that in the Assembly Key file value in the project properties.

Step 3: Compile and deploy the Maps project

From project properties in the Solution Explorer window, deploy the project. Check in GAC to see if the DLL is deployed. Note down the public key token from the file properties in GAC.

Step 4: Build the Dynamic Maps orchestrations

Add a new BizTalk project OrchestrationForDynamicMaps. Create a new Orchestration and name it Orch_DynamicMaps. In the Orchestration View window, create the following variables and messages. Set the value as in the table below. Leave the rest of the values as their default values.

Message / VariableIdentifierTypeComments
MessageGeneric_InDynamicMaps.GenericInSchemaThe incoming Message
MessageMessage_OutSystem.Xml.XmlDocumentThe outgoing Message
VariableSubscriberInformationSystem.StringPromoted Subscriber Info
VariabletMapSystem.TypeThe Map value

The orchestration built looks as in the figure below. The outline of steps is detailed below. You can download the source and follow the steps conceptually.

Image 6

  • Add a Receive Port Receive_GenericMessage which accepts the Generic_In message declared above.
  • Add an Expression Shape Identify Subscriber and set the expression value as below:
    SubscriberInformation = 
       Generic_In(DynamicMaps.PropertySchema.SubscriberInfo );
  • Add a Decide and check if SubscriberInformation == "ABC" or SubscriberInformation == "XYZ", and a branch for termination.
  • Add an Expression Shape and name it Set Map and put the value.

    Change the public key token value to the value you noted down previously.

    tMap = System.Type.GetType("DynamicMaps.Map_ABC, 
             DynamicMaps, Version=, Culture=neutral, 
  • Add a Message Shape and do the dynamic transformation and dynamically set the Send port. These are the magic lines:
    transform (Message_Out) = tMap(Generic_In);
    Dynamic_Send(Microsoft.XLANGs.BaseTypes.Address) = 
         "FILE://C:\\Ports\\ABC\\%MessageID%.xml" ;
  • In the second branch for subscriber XYZ, we set the map to the map for XYZ and change the public key.
    tMap = System.Type.GetType("DynamicMaps.Map_XYZ, 
             DynamicMaps, Version=, Culture=neutral, 
  • Now we need to construct the message like ABC's. Alternately, you can construct the message in the Expression Shape directly, but you would need to add the construct keyword.
    construct Message_Out
        transform (Message_Out) = tMap(Generic_In);
        Dynamic_Send(Microsoft.XLANGs.BaseTypes.Address) = 
                "FILE://C:\\Ports\\XYZ\\%MessageID%.xml" ;
  • Add a Send port which sends out a message of type System.Xml, and use that to send the transformed file to your desired destination.
  • Compile and deploy the project.

Note: In essence, what we have done in the step above is to use the reflection feature in .NET and find the type of the Map. Then we use the variable and invoke the transformation by using the BizTalk internal keyword transform. BizTalk does all the hard work of loading the assembly dynamically for our use and unloading the assembly later, and all that plumbing that you otherwise need to write. Don't you love BizTalk now?

Step 5: Testing and Output

You can drop the two test files and you will get two different outputs for the same file based on changing the subscriber.

I have the inputs and outputs as below:

  • Input file for party ABC

    Image 7

  • Output for party ABC

    Image 8

  • Input file for party XYZ

    Image 9

  • Output for party XYZ

    Image 10

Step 8: A few notes on the output

The output is self explanatory, and you will notice that for identical inputs except for the party name, the output was different based on the maps used. We used a Time functoid to generate the time, and the other values came from fixed strings. And last but not the least, I confess, I am not 22 as the example file indicates or misleads, way older than that! My wife was quick to point that one out.

Points of Interest

Although in this example we have used a simple Decide shape to figure out which map to load, in real life implementations, this could be a database helper class which returns the name of the map assembly from a SQL database or a similar design. This design is useful since you can add more maps and systems even after the original system has gone live. This is possible because you can add a new subscriber into the database and have a new DLL with the corresponding schema and maps. This provides a loose-coupling which is highly desired in these scenarios.


In the declaration of the variable tMap, I could not get it to be defined as System.Type from the dropdown. I had to open the .odx file in Notepad and set it manually after choosing a random type initially.


A very common exception would be:

Error in accessing the part data or one of its fragments. 
The part or fragment may not exist in the database.

When this happens, make sure you have both the assemblies deployed and they are present in the GAC. Also check that the ports are created and the Receive port uses an XML transmit pipeline and the Send port uses a pass-through transmit pipeline. If that did not solve the problem, ping me at the BizTalk cafe forums. I would be glad to take a look.


  • Version 1.0 - March 20, 2006.


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

Written By
United States United States
Abhilash is from Kerala, South India. He is presently working as an Integration Consultant for many fortune 500 companies in his current role at Neudesic

Abhilash has been programming since he got his first PC, when they used to load BASIC using tapes. He got his first real PC in 1994 - a 286 with a 40 MB hard disk, 1 MB RAM, and a 5.25 " FDD with a HGA graphics card.

Pascal was his first favorite programming language. And he thought at one time that it was the greatest language. He never really got on to the Delphi wagon, but went with C++, and then progressively VC++ SDK, MFC, COM, and then eventually chose C# as his preferred language once .NET came along. With the emergence of SOA into mainstream, Abhilash chose BizTalk as his SOA realization tool of preference. He opines that BizTalk helps implement SOA; by so clearly separating the message and the underlying implementation, and connect apps purely based on contracts. This is what many classic technologies like IDL tried to do, but somewhere, the point got lost. BizTalk is his tool of choice for EAI. Abhilash has worked in various platforms including Win32,.NET,Linux, and Mainframes and has professional experience in embedded development and voice telephony.This helps him understand the EAI domain better.

His passions include programming, blogging ,cricket and chess. He likes to troll MS user groups and used to run a site as a hobby. The site has a forum, so if you work with BizTalk server, he would like to hear about your experiences there.

He was awarded Biztalk Server MVP in April of 2006.

His life events gets recorded here You can connect with him on Linkedin

Comments and Discussions

QuestionDynamic Mapping Pin
Member 1041737123-Nov-13 3:04
Member 1041737123-Nov-13 3:04 
QuestionDynamic Maps Testing Pin
Member 103233348-Oct-13 4:57
Member 103233348-Oct-13 4:57 
GeneralGreat Article Pin
Dipti Mehta12-May-11 20:39
Dipti Mehta12-May-11 20:39 
GeneralRegarding to sample Project Pin
harshil12349-Apr-09 4:24
harshil12349-Apr-09 4:24 
QuestionHelp in Biztalk Mapping for table looping.... Pin
Member 347355320-Jun-08 8:39
Member 347355320-Jun-08 8:39 
GeneralDo it only in development box.. Pin
Member 27045595-May-08 10:06
Member 27045595-May-08 10:06 
GeneralGreat Article Pin
Manikandan.net21-Nov-07 22:18
Manikandan.net21-Nov-07 22:18 
GeneralUsage of Biztalk Map Pin
RSArockiam20-Mar-07 20:26
RSArockiam20-Mar-07 20:26 
QuestionRegarding Customizing own pipeline Pin
ashwini_se8-Mar-07 3:40
ashwini_se8-Mar-07 3:40 
GeneralAlternative Approach to Dynamic Maps Pin
David J Carroll23-Mar-06 7:47
David J Carroll23-Mar-06 7:47 
GeneralRe: Alternative Approach to Dynamic Maps Pin
_ABHILASH_MS_23-Mar-06 8:19
_ABHILASH_MS_23-Mar-06 8:19 
QuestionHelp on Biztalk mapping... Pin
Member 347355320-Jun-08 9:33
Member 347355320-Jun-08 9:33 
General5! Another good one! Pin
Nish Nishant21-Mar-06 10:01
sitebuilderNish Nishant21-Mar-06 10:01 
GeneralRe: 5! Another good one! Pin
_ABHILASH_MS_22-Mar-06 0:15
_ABHILASH_MS_22-Mar-06 0:15 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.