What the BizTalk Server 2013 Mapper Updates Mean for You

By Nick Hauenstein

This blog post represents the first in a weekly series that will highlight things you need to know about new features in BizTalk Server 2013. This week we will look at the new mapping engine and how the underlying changes in the engine might effect the behavior you see when using the BizTalk Mapper.

If you look at the list linked above, you find this:

The Mapper uses the XSLCompiledTransform class. Previous BizTalk Server versions used the XslTransform class, which is obsolete. The XSLCompiledTransform class provides performance enhancements, including:

  • Once the Load method completes successfully, the Transform method can be called simultaneously from multiple threads.
  • The new XSLT processor compiles the XSLT style sheet to a common intermediate format. Once the style sheet is compiled, it can be cached and reused.

For more information on the XSLCompiledTransform class, go to XslCompiledTransform Class.

The mapper now uses the XslCompiledTransform class, a class which was the result of a redesign of the XSLT architecture in the Visual Studio 2005 release (.NET 2.0 timeframe).  While load time of a transform using this class can be longer (since the transform must be compiled upon load), if cached it can yield a 4-fold performance improvement for transforms. Will we see this same level of improvement when used within the context of a BizTalk map? Not quite, but it will definitely be noticeable.

There is a fairly detailed blog post on the XslCompiledTransform class from the XmlTeam written around that time as well. I’m not going to re-hash all of that content here, though you should definitely take a look at the table under the Discretionary Behaviors heading. That table will unveil some things (read: strange edge cases) that used to “just work”, but will now cause exceptions.

Instead of focusing on performance improvement or weird edge cases, in this post, I wanted to look at something a little more common. It surfaced for our team as we were migrating some custom functoids from BizTalk Server 2010 to BizTalk Server 2013. Essentially what we found was that if you attempted to return a null value from a custom functoid, you would receive this error message:


For the benefit of those using Google-fu to attack the same problem, the exception message reads: “Extension functions cannot return null values.”

Really this exception would occur regardless of using a custom functoid. Indeed, you can re-create the same behavior with a Scripting functoid returning null out of an inline C# method.

How to Return Null

This all begs the question, how am I supposed to return null? Well there are a few different cases to consider.

If you’re returning null because it’s cleaner than an empty string, but empty string is not considered a special value on its own, then it’s fairly simple. Toss a null coalescing operator between whatever value might be null and string.Empty. That was the fix that handled our case nicely:

[sourcecode language=”csharp”] public string GetError(string lookupId)<br>{<br>return CachedDatabaseAccess.GetError(new Guid(lookupId)) ?? string.Empty;<br>} [/sourcecode]

While that will cause the desired result in the destination message in this case, if I wanted to output null to the destination message I have a few choices still. I can still return string.Empty which will create an empty node in the document, use one of the Logical functoids to prevent a node from being created when it does not return true, or use the Nil Value functoid to set set the output as nil (assuming the destination schema allows it).

Passing Null Around

But what if I’m returning that null value so that it can be passed to another functoid? If both are scripting functoids and they’re both using inline script, I can do this quite easily by making use of a global variable within the map (in the screenshots below it is named result1), and then writing my code to access that in order to request the raw result.

NOTE: This is also a pattern we encourage for maintaining the state of .NET objects through chained functoids (since if they are returned directly the ToString method is called)



That’s all fine and good when things are inline C#, but what if I’m wanting to pass an earlier null value as an input to an external assemblies? Well that’s where things get a little bit trickier. Best bet there right now is to establish a special non-null value that can represent null, and pass that to an external method that wraps a call to the method you actually want to call and translates that value. Either that, or write custom functoids that can share a set of ThreadStatic values and have one of them wrap the call to the external method (though that might be a little bit overkill).

Wrapping it Up

Even though I’ve spent my time talking about one small annoying aspect of upgrading, let me tell you it’s a worthwhile price to pay for the massive performance improvements you’re going to see.

If you want to see how that custom functoid turned out, and interact with it yourself, be sure to check out one of our upcoming BizTalk Server 2013 Developer Deep Dive courses!

See also:

4 thoughts on What the BizTalk Server 2013 Mapper Updates Mean for You

  1. Pingback: itHero | “Extension functions cannot return null values.” Exception when running a map in BizTalk 2013

  2. Pingback: BizTalk Server 2013 New Features Series Index | QuickLearn Training Blog

  3. Pingback: BIZTALK SERVER 2013 NEW FEATURES SERIES INDEX | venneker.net

  4. Hi,

    I have upgraded my previous BT 2010 applications to BT 2013 R2. I get an error stating: “Attribute and namespace nodes cannot be added to the parent element after a text, comment, pi, or sub-element node has already been added.” during transformation.

    Looking at my mapping, this makes perfect sense as I am trying to insert attributes post added sub-elements. As I understand it XSLCompiledTransform flags this as an error, whereas the previous XslTransform ignored it. Now, I still want to ignore this. Is there a flag I sent set to XSLCompiledTransform in able to accomplish this?


Leave a Reply

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