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”
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()" /> <ns0:SAPOrder> <OrderId> <xsl:value-of select="Orderheader/OrderNumber/text()" /> </OrderId> <ClientId> <!-- This is a dummy value, in real scenarios we probably get this value from an external system or DB base on the client name--> <xsl:text>1</xsl:text> </ClientId> <Dates> …
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.
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)
16 thoughts on “BizTalk Mapper: Best Practices when using Custom XSLT files”
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.
Never face this problem before and I don’t know if still exist in BizTalk Server 2010/2013… but nice to know.
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.
“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
I agree completely with “BizTalk Mapper and custom XSLT together”!
Regarding TIP 2: Give it a proper name
Maybe it’s better to give it the same name as the map. Then you know that it “belongs” to the map.
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.
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.
Last comment above is a good tip. Use exactly the same name in both btm and xslt files.
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.
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.
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.
Reblogged this on Gihan's Blog.
Hi Sandro, I used custom XSLT transformation in BizTalk 2010 with no issues but when upgraded to BizTalk 2016 having message transform issues.
What is the issue?
Got ‘NullReferenceException’ from transforming the message and didn’t transformed either.