BizTalk Server: Demystifying the Test Map operation in Visual Studio

Posted: January 7, 2014  |  Categories: BizTalk Maps

In the past, I wrote a series of post on Basics principles of Maps where I stated that testing should be a continuous process as you build your map, not only at the end of development but when necessary or when an important mapping block is complete.

And the good thing is that this feature is available to developers in an easy manner and directly from our favorite development tool – Visual Studio – without the need to build and deploy the maps or even create and configure ports and test them in runtime.

Note that Visual Studio allows you also to Validate and Debug maps at design time.

For this we need to:

  • Open the Solution Explorer windows
  • And execute the test by right-clicking the map name and selecting “Test Map” option
  • Verify the results in the Output window.

By default, an instance of the input schema is generated automatically with dummy values, according to their type, and tested in the selected map. In the end, the generated result of the errors that occurred is displayed in the output window.

Visual Studio Output Window

However, this scenario probably is not the ideal one and what we want is to test the map with an existing and real message and not a dummy one. And the good news is that, again, BizTalk Mapper allows us to specify a source document.

In addition, it also supports instances as native (CSV, EDI …) or Extensible Markup Language (XML) as input or output according to the scenarios.

For this we only need to configure the properties of the map before we execute the test:

  • Right-clicking the map name and select Properties option;
  • In the Properties window set “TestMap Input Instance” property with the path to the input instance message file to be used while testing the map.
Visual Studio Map Properties Windows

Other important properties that you can specify are:

  • TestMap Output Instance: Specifies the location where the Test Map should generate the output message.
  • TestMap Input: Specifies the format of the input instance message.
  • TestMap Output: Specifies the format for the output instance message.
  • Validate TestMap Input: Specifies whether you want to validate input instance messages against the source schema before you test the map.
  • Validate TestMap Output: Specifies whether you want to validate output instance messages against the destination schema after you test the map.

This last option, “Validate TestMap Output”, of the map properties is extremely important for the partial tests of maps. By setting this property to “False”, allows us to test an incomplete map without being shown errors due to lack of mandatory data, many of them associated with areas still to map.

This is nothing new, despite we often forget some of these properties. However I find myself constantly hear that, despite being easy to test one-to-one maps inside Visual Studio at design time, when we have multiple inputs to the map, many-to-one or many-to-many transformations, the same doesn’t happen, and it’s impossible to test this type of maps inside Visual Studio at design time because we only can specify an input message… and that it’s not true!

How can we test many-to-one or many-to-many maps inside Visual Studio?

Testing one-to-one maps are extremely simple and straightforward, however, many-to-one or many-to-many maps, despite being simple to test, it will require some additional steps.

First, you have to understand that, Visual Studio doesn’t let us define multiple native instances in the “TestMap Input Instance” property, it only allows one message instance. But when a map has multiple source schemas, they are wrapped in a hierarchy multi-part message created by BizTalk.

So the only way for us to test this type of maps is to provide with an instance of the message in the “TestMap Input Instance” property that matched with the hierarchy multi-part message created by BizTalk.

The question here is how we can easily create an instance of a multi-part message?

And the question is simple, by using the default behavior of the Test Map operation to make this work for us!

Let’s explain better, when we create a new map the “TestMap Input” and “TestMap Input Instance” proprieties are defined by default as: “Generate Instance” and “” (empty) respectively:

Visual Studio Map Default Properties Windows

As I explained earlier, this means that if we test the map without changing these properties, one message instance will be generated automatically with dummy values. However, in these scenarios, it will generate a dummy instance of the multi-part message expected by the map! AWESOME!

So what we need to do is:

  • Right-clicking the map name and selecting “Test Map” option
  • In the Output window, the BizTalk Mapper will provide a link to the test’s output XML file and also to the input XML file.
Visual Studio Output Window input and output file
  • Through the File Explorer, go to the directory folder specified in the Output window to have access to the dummy input file:
    • In this case: “C:\Users\Administrator\AppData\Local\Temp\1”
  • Copy the file to your project folder, in this case: “inputfile.xml”

This is a sample of this file:

multi-part message input sample

As you can see, all the different input messages are there, with the right namespaces and so on… So what we need to do now is to:

  • Edit this file and put the User and Address messages that you want (you can do this easily with notepad)
  • And then specify the “TestMap Input Instance” property with this file.

As said earlier … we need some additional steps … but it is extremely easy to accomplish!

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.

4 thoughts on “BizTalk Server: Demystifying the Test Map operation in Visual Studio”

  1. How would you automate this scenario in continous integration? VS out of the box unit testing is not that helpful….The above works for a dev to validate the map for sanity check….

Leave a Reply

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


Back to Top