Migrating BizTalk Server maps to Azure BizTalk Services maps

Article
1/17/2024

Introduction

Unlike schemas that you will be able to directly take your BizTalk Server schemas and use them in you Azure BizTalk Services solution, BizTalk Maps needs to be migrated because despite the Transform Designer (mapping tool used for Azure BizTalk Services) and the BizTalk Mapper Designer looks mostly the same in terms of layout and user experience, they are quite different and the underlying map format is different. Basically when we are using BizTalk Mapper Designer the transformation are created using XSLT, however with Transform Designer the transformation are created using Extensible Application Markup Language (XAML).

Also the available functoids, that are now called Operations, are different as well. Not all the functoids available in BizTalk Server are available as map operations in Azure BizTalk Services and there are new Operations that doesn't exist in BizTalk Server like: several List Operations, DateTimeReformat, GetContextProperty and so on. And despise XSLT and custom C# are supported the concept of "Scripting" map operation in Azure BizTalk Services Transforms are limited comparing to BizTalk Service for example:

You cannot use custom inline XSLT, you only can custom XSLT code directly to override Azure BizTalk Services map, similar to the “Custom XSLT Path” map grid properties in BizTalk Server.
You can only use CSharp Scripting inside BizTalk Services maps.

Because of all this reasons you cannot directly use a BizTalk map in Azure BizTalk Services.

How can you migrate BizTalk Server maps to Azure BizTalk Services maps?

Basically you have two options that you can use to migrate BizTalk maps:

By using custom XSLT code gathered from your BizTalk Maps (...the easy way)
Or by using the BizTalk Map Migration Tool provided by Microsoft.

Using BizTalk Map Migration Tool

The BizTalk Map Migration Tool is available in the tools zip file of the Microsoft Azure BizTalk Services SDK (it used to be on Codeplex at BTM Migration Tool but this is now a dead link). This is a command line tool, provided by Microsoft that takes the following inputs

A BizTalk map (.btm)
Optional. Resulting BizTalk Service project Transform (.trfm)

And that will try to produces the new mapper (.trfm) file as an output. But before you use this tool you need to know that:

This tool expects that the machine on which it'll run would have both products installed: BizTalk 2010 or above and Azure BizTalk Services.
And the schemas should be present as expected by the BTM map (in the relative folders).

Limitations

I’m saying “that will try” because there are many limitations present like:

Certain functoids may not get converted by this tool, for example some Scripting and Custom functoids from BTM way cannot be converted. In this case they are converted to arithmetic expression functoid in the TRFM map with the expression value as empty.
Links to functoids, which cannot be converted successfully, are denoted as empty inputs in the new TRFM functoids.
Certain features that are not supported, yet, in TRFM, will not be converted properly. For example, links from xs:extension node(s) are not converted to TRFM
Certain conditional mapping are not converted as expected as these features are not yet implemented in the Transforms
And so on.

At the end this tool will generate a conversion process report (Report.txt) listing out the failed conversions.

Also in terms of Organizing and Documenting Maps there are two drawbacks presents:

Labels and comments from the BTM functoids are not mapped onto the TRFM functoids
The multiple pages from BTM are translated to a single page in the TRFM map to ensure all operations within a scope are within a page.

Sample

Let’s look at one very easy example and analyze the end result. In this scenario we have two different records, Client and Employee, and we want to map all the man’s clients and employees to Person (Sex == M). This is look of the BizTalk Server maps:

When we apply the BTM Migration Tool it will generate this nice BizTalk Service map for us:

And the good news in this case, if we try the map it will successfully work and it will produce the tight output! (Yes I looked for a good sample). However is this the perfect output?

So let’s try change this to get only the female sex present in the input message. It seems an extremely easy change to make… we just need to go to the Logical Operation present in each MapEach Loop Operation and change the condition:

However surprisingly the output instance after this change is empty.

So why this happens? In this case, after looking to all the shapes, I found out that the MapEach Loop operation also as the same condition that is present in the Logical Operation that we need to change, as you can see in the picture below:

Can this map be improved?

The aim of this article is not to explain the functionalities of the new map and how the new operations works, however if you look at the map generated by the compiler, at least in this case, you can easily identify that we can simplify the map to be more easy to read and to maintain, by:

Maintaining the condition in the MapEach Loop operation
Suppress all the Logical and Conditional Assignment Operations that are inside the MapEach Loop operation
And use direct links to map the Name and Sex

So as a final note, even if the migrator tool did a decent job, you should always try to identify some bottlenecks, problems or overlaps and simplify it.

Using Custom XSLT Code

Migrating maps from BizTalk Server solutions to Azure BizTalk Services could be one of the more complex artifacts to migrate (depending on map complexity)… or not!

The good news is that, you don’t necessary have to remake or migrate our BizTalk map to BizTalk Service map. As I mention earlier BizTalk Service maps support custom XSLT code, you can use a custom external XSLT file, similar to the “Custom XSLT Path” map grid properties in BizTalk Server to override BizTalk Service map and use custom XSLT to make the entire map transformation.

I try to avoid using Custom XSLT files for solving a mapping problem, for many reasons, however there are always exception. I do recommend using custom XSLT files:

If you are dealing with huge message and High Performance is one of the primary requirements (and even then this maybe can be avoid)
Or if you already have a custom XSLT file provided by another team, or from another system that you can re-use in your map. In this case don’t try to reinvent the wheel!

And because we are migrating a BizTalk Server map we already have the XSLT, so for me there is no point spending a few and in some case many hours trying to remake the same transformation in a different editor.

How To extend Azure BizTalk Services maps to use custom XSLT code

To extend your BizTalk Service maps to use custom XSLT code you must:

Go to the grid properties (or also call Transform design surface properties) in the Transform Designer, where you can see that there is a XSLT property in which we can extend the map to use custom XSLT code

Note: This time Microsoft did a nice work and if you notice in the grid page there is message that will help you.

In Properties, click XSLT, and click the ellipses (…). A Configure XSLT dialog window is opened.

To import an existing XSLT file, click Import XSLT. Browse to the .xslt or .xsl file and click Open. The imported XSLT populates the Configure XSLT dialog window. OR, enter the XSLT syntax in the Specify the XSLT below … window.

Optional. To import an existing XML extension file, click Import EXTXML. Browse to the XML file and click Open. The imported XML populates the Specify the extension objects … dialog window. OR, enter the XML syntax in the Specify the extension objects … window.
Optional. Click Use XslCompiledTransform for better performance to transform XML data by compiling XSLT style sheets and executing XSLT Transforms. When the style sheet is compiled, it can be cached and reused. Otherwise, the XslTransform class is used; which is best when executing a Transform on one occurrence.
Click OK.

When XSLT is used, the Transform design surface is grayed out. XSLT can be specified for every Transform file (.trfm).

How do I generate XSL output from the BizTalk Mapper Designer?

To generate a XSLT file that represent you BizTalk Map you just need to:

Open the BizTalk map in Visual studio
Right click on the map and select “Validate Map” option, this operation will generate the XSLT and you can see the path of generated XSLT in output window.

You can use this XSLT, without change it in most of the cases, to add in your BizTalk Service Maps.

Code Samples

All of this sample can be found and downloaded in Microsoft Code Gallery:

BizTalk Maps can be found here: BizTalk Server – Basics principles of Maps
BizTalk Services map samples can be found here: Migrating BizTalk Server maps to Azure BizTalk Services maps

Share via