BizTalk: XTransformationFailureException on mutli-part XSLT map.

Microsoft.XLANGs.Core.XTransformationFailureException: Error encountered while executing the transform XXX.MyMap. Error:Transformation failed.. ---> Microsoft.XLANGs.Core.XTransformationFailureException: Error encountered while executing the transform XXX.MyMap. Error:Invalid input/output document into/from the transform. Does not have a single root node..

Ya what now?

I received this error message when using a multi-message map in BizTalk.

If you need to use multiple messages on either side of your map, then you can do this with BizTalk.  You have to define your map from the Orchestration Transform shape, but selecting all the input, or output, messages that you wish to use.

Visual Studio will then update the schema used in the map dynamically with a custom schema that contains all your messages, wrapped up in a schema of type http://schemas.microsoft.com/BizTalk/2003/aggschema#Root.  Each message will be embedded in an element named InputMessagePart_X, where X is a zero-based sequential number.  The runtime takes care of this combining of messages when the map is called.

A repeating InputMessagePart node would arguably be more flexible, but hey.

In my particular situation I had multiple input messages and one output. Using the Test Map action on the map file, Visual Studio can generate you one of these aggregate messages for you (which you can then easily customise the message parts with test data).  My map worked just fine within Visual Studio, but not in BizTalk at runtime, and I received the error above.

Logically, it would seem like the problem was with the inputs, as I had multiple - I assumed that for some reason BizTalk wasn't wrapping up the inputs into the aggregate schema and creating multiple root elements.

TLDR;

I was incorrect.  The issue actually lay in the output - I was using Custom XSLT (although I'm not sure if it's exclusive to XSLT maps), and I needed to exclude the XML declaration (that's the <?xml version="1.0" encoding="utf-8"?> bit) in the output message.  I'm not sure why this is, as there is only a single output, my assumption is that there is some sort of "multi-message mode" in BizTalk that will expect both sides to be wrapped up - having an XML declaration midway through a message (e.g. if it was wrapped in an envelope message), would be invalid XML.

<xsl:output method="xml" omit-xml-declaration="yes"/>

Setting omit-xml-declaration excludes the XML declaration from the top of the output, and somehow everything starts working.

Remember when making changes to XSLT files, you will need to force a rebuild to your project as Visual Studio doesn't pick this up as a change, even if you have the XSLT included in the project.