BizTalk Mapper: Best Practices when using Custom XSLT files

Posted: January 20, 2014  |  Categories: BizTalk Maps

If you follow my blog or already saw one of my presentations in BizTalk innovation Days events about BizTalk Mapper Patterns and Best Practices, you already notice that I avoid using Custom XSLT files for solving a mapping problem.

I only 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 avoided)
  • 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!

But again, this is my personal opinion. You may argue that XSLT automatically generated code by the BizTalk mapper compiler cannot perform as well as the personal Custom-XSLT code! And yes, I agree with you… in most of the cases… but it also depends on the approach that you are implementing to solve the problem.

the real secret is to find the best of both worlds: BizTalk Mapper and custom XSLT together. I can spend many hours discussing this topic, and this will also be addressed in my upcoming eBook in more detail, however, I let you with two statements:

  • In most scenarios you wouldn’t really notice too much difference between using the BizTalk Mapper and a custom XSLT file;
  • I can prove to you that using properly the BizTalk Mapper can have the same performance that a custom XSLT file! (of course, that can always be exceptions)

However, if you are using an external XSLT file at least you should follow some of these best practices:

TIP 1: Always Add your custom XSLT files to the solution

You should always add the External custom XSLT files to your solution so that they can be easily found and can be added to the source control.

TIP 2: Give it a proper name

Don’t call it “ExternalXSLT” or “CustomXSLTCode”, give it a proper name to the custom XSLT file that could identify the map.

  • For example: “<name of the map>-XSLTFile.xsl”
custom xslt file proper name

TIP 3: Add Standard XML Comments

You should add standard XML comments: “<!– Comment –>”, inside the custom XSLT code. As many time you think that it is important to explain little parts of the process/code.

<xsl:template match="/s0:Order">
   <xsl:variable name="var:v1" select="userCSharp:GetCurrentDateTime()" />
         <xsl:value-of select="Orderheader/OrderNumber/text()" />
        <!-- This is a dummy value, in real scenarios we probably get this value
        from an external system or DB base on the client name-->

TIP 4: Rename the page grid

If you are using an external XSLT file, at least rename the default grid page (Page 1) to a name that draws attention to this fact, for example: “ThisMapUseAnExternalXSLTFile”. At least this way new BizTalk developer can easily read and understand that this map is using an external XSLT file.

Rename the page grid custom XSLT file

Note: The best part of being a speaker at BizTalk events, is that we can discuss with the attendees and get feedback. I really love this part! And this last tip was given by Mikael Sand while we were discussing this topic, probably while we were taking a beer in Norway 🙂

Feel free to comment or add more tips to implement best practices.

You can download the source code from:
BizTalk Mapper: External Custom XSLT file vs BizTalk Mapper (Best Practices)BizTalk Mapper: External Custom XSLT file vs BizTalk Mapper (Best Practices)

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.

16 thoughts on “BizTalk Mapper: Best Practices when using Custom XSLT files”

  1. Very Nice Sandro. I remember that just once I had to use Custom XSLT files, because in Biztalk 2006 had a issue: If you use many functoids in a mapper, you get many problems with it, and just don’t work. I don’t know if this issue was corrected in Biztalk 2010 or 2013.

  2. Nice points. Will definetly be incorporating these as I personally use custom xslt for maps and feel using custom XSLT files are gud because of easy maintainability , extensibility , performance, and can be used for dynamic mapping and extensibility of using cache etc for more performance improvement.

    1. “Using custom XSLT files are good because of easy maintainability, extensibility, performance,…” > I really understand these points, but we can have a long discussion about this 😀

      I hope to approach this in more detail in my upcoming eBook about BizTalk Mapping Patterns and Best Practices

    1. Give it the same name is a good approach. But really the key point here is whether is the same or similar name, is in the same directory or not, is that the name needs to properly identify the map.

      1. When we use custom XSLT my advice is to use exactly the same base name. When they have the same base name the are listed together in the solution explorer (and other directory listings, such as the version control system). When you have large solutions with several folders, this is crucial for navigation within the solution.

  3. I prefer using (and advice others to use) custom XSLT files mainly because of their easy maintainability and better support for commenting. Tracking changes in version control is also way easier when using XSLT. Plus for me, XSLT is easier to read.

    Anyway, I think it’s better not to mix custom XSLT and graphic mappings, but to choose either way and use it consistently in solutions.

  4. Hi Sandro nice post. Another reason I would use Custom XSLT is to resolve complex grouping problems. I know there are ways using the mapper but I would always opt for Custom XSLT for grouping.

  5. Thanks Sandro, I often use XSLT if the maps involve sorting, grouping and cross lookups. Also, it is easier to track changes in source control system.

  6. Hi Sandro, I used custom XSLT transformation in BizTalk 2010 with no issues but when upgraded to BizTalk 2016 having message transform issues.

Leave a Reply

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


Back to Top