How to encode XML sent from BizTalk
XML sent from BizTalk through a Send Port will, per default, always be encoded as UTF-8.
When XML is encoded as UTF-8 no encoding and XML declaration is needed, so if using a PassThruTransmit Pipeline, the XML output will be UTF-8 with no declaration:
Shown in Internet Explorer like this:
Changing the Encoding
In certain cases, changing the default encoding might be required for various reasons:
- Sending XML to legacy systems where only XML files saved as ANSI are permitted.
- Sending XML to some custom build XML parser that, for some reason, requires another encoding than the UTF-8 standard.
Changing the encoding should be fairly easy, after all BizTalk’s specialty is XML!
Unfortunately this is not quite the case and, as you shall see in this blog, it does require some unexpected configuration, coding and possibly even some hacks!
Let us start by examining what we have out-of-the-box when working with BizTalk:
There is an XMLTransmit Pipeline that should be able to do the trick; let’s give it a try:
When sending a message through the Send Port above, we are left with an XML document still encoded in UTF-8 and now it actually has a declaration!
As it turns out, it doesn’t matter what you write in the TargetCharset property, you could write “DonaldDuck” for that matter, the Pipeline would still “work” and UTF-8 would still be submitted.
This bug/behavior has to do with the fact that the property set on a Port is simply not saved in the Property Bag. The Pipeline Component will always use the TargetCharset set on compilation time of the Pipeline, and in the case of XMLTransmit, this is blank (default: UTF-8).
Build your own
So if we have a target system that requires XML documents with another encoding than UTF-8 we need to build our own Pipeline.
By creating our own Send Pipeline and choosing the XMLAssembler Pipeline Component in the Assemble stage, we can choose Target charset from a drop down list.
Choosing Little-Endian-UTF16 (1200) and deploying and using the new Pipeline will now give us XML with the following declaration:
Let’s examine the configuration of the new Pipeline:
The TargetCharset reads Little-Endian-UTF16(1200), but changing the regular XMLTransmit Pipeline to the same (or 1200 or UTF-16 or anything else) will not make a difference, XMLTransmit will always produce UTF-8, no matter what is placed in TargetCharset.
So now we have managed to change the encoding by creating a custom Pipeline. However the drop down list is somewhat limited and it is not possible to specify your own encoding (at least not in the Visual Studio interface).
Let’s assume that we need to use the ISO-8859-1 (Western European) encoding. This is a very common encoding used for systems that can only read ANSI files but still needs Western European characters in the XML document.
To our surprise this very common encoding is not part of the encodings we can select.
This is where we need to hack the system!
First we need to find the Code Page for ISO-8859-1:
Next open the Visual Studio Pipeline file (.btp) and insert the following:
Open the file in Visual Studio and you should now see ISO-8859-1 shown in the Target charset property.
Redeploy your Pipeline and the output should now appear as follows:
It’s not pretty but it works. And once you have made a custom Pipeline that encodes to ISO-8859-1 (or some other encoding required), the Pipeline can be placed in a common BizTalk Application and reused for all Send Ports that requires sending XML with this particular encoding.
Easy Tracking in BizTalk Server: