Two Issues with Variable Initial Values

When doing a build of a BizTalk Orchestration, I saw this error:

illegal escape '\I'
illegal escape '\C'
illegal escape '\D'

The issue was that I had an orchestration variable that had the following ”
“inital value” (in the properties window): “e:\Integration\Config\DL.TL2000.Shipment.config.
Just like in C#, changed to add the @ sign so that blackslash would not be an escape character.

Similar Common Issue

If you put the set the initial to a string such as ‘abc’, but you don’t put in quotes around, you will get these two error:

1) identifier 'abc' dos not exist in "OrchestrationName'; are you missing an assembly reference.
2) cannot find symbol 'abc' 

I needed to implement RawString functionality to be able to read a non-XML file into an orchestration. Scott Colestock had a great article on this on his TraceOfThought blog, but when I needed it the other day, it had been hacked (hopefully only temporary).

1. Deploy the C# code towards the bottom of this log; it is not a pipeline, so can be added to new class to an existing C# helper library you might have, or you can put it in its own assembly.

2. Add a reference to this C# Assembly in your orchestration.

3. In your orchestration, create a multipart message type. It will have only one part, but that will be the RawString class from the code below.

4. In the orchestration, create a nessage of type System.Xml.XmlDocument, and assign this to your cativating receive. But wait Neal, I thought you said we wanted to receive a non-XML message. Trust me, this will work.

5. In the orchestration, add a Message Assignment shape and code similar to below:

//convert the message received to a new message with a multiple-part-type of RawString 
msg_rcv_RawString.MessagePart_1 = msg_XML_Doc; 

6. At this point, you can access the message as a string, for example:

varText = msg_rcv_RawString.MessagePart_1.ToString();

Voila – you have now have the text of the file in a variable called varText. You can then parse it, or do whatever you want with it.

The code below needs to be in a C# helper class that you can access within your orchestration. (Obviously give it a strong name and GAC it.) I can’t remember which site I got this code from, but I think it’s out there on several.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Xml;
using System.Xml.Serialization;
using System.Runtime.Serialization;
using System.IO;
using Microsoft.XLANGs.BaseTypes;

namespace REI.BizTalkNonDB.Helpers

    public abstract class BaseFormatter : IFormatter
        public virtual SerializationBinder Binder
            get { throw new NotSupportedException(); }
            set { throw new NotSupportedException(); }

        public virtual StreamingContext Context
            get { throw new NotSupportedException(); }
            set { throw new NotSupportedException(); }

        public virtual ISurrogateSelector SurrogateSelector
            get { throw new NotSupportedException(); }
            set { throw new NotSupportedException(); }

        public abstract void Serialize(Stream stm, object obj);
        public abstract object Deserialize(Stream stm);

    public class RawStringFormatter : BaseFormatter
        public override void Serialize(Stream s, object o)
            RawString rs = (RawString)o;
            byte[] ba = rs.ToByteArray();
            s.Write(ba, 0, ba.Length);

        public override object Deserialize(Stream stm)
            StreamReader sr = new StreamReader(stm, true);
            string s = sr.ReadToEnd();
            return new RawString(s);

    public class RawString
        string _val;

        public RawString(string s)
            if (null == s)
                throw new ArgumentNullException();
            _val = s;

        public RawString()

        public byte[] ToByteArray()
            return Encoding.UTF8.GetBytes(_val);

        public override string ToString()
            return _val;


The following is the generally document way fo doing this:


However, sometimes, for no apparent reason, it won’t compile, or at least shows a “red dot” on the upper right corner of the expression shape, even though it is technically correct. Sometimes if you open it, and close it, or move it and move it back, then the error will go away. But this is a bug, and should not be required.

New alternative way to get the Orchestration InstanceID:

strProcessId = System.Convert.ToString

YourOrchestrationName is the TypeName found in the Orchestration Properties.

This has not caused the “stupid” problem of the compile errors and having to touch the shape, and move it.

One way to check for missing data is to do an xpath count.

The two-step approach (put the xpath in a variable first). Some might find this code cleaner, but you use a variable. Note that you have to use the conversion statement to convert the string result of the xpath to a number, if you need to test that number as I do in the following “if” statement.


strCountMessageKeysXPath = "count(//*[local-name()='MessageKey']";

intCountMessageKeys =

// Yes you can put if statement in expression shapes (but not message assignment shapes) 
if (intCountMessageKeys >= 2) 
   strXPath = "//*[local-name()='MessageKey'][2]"; 
   strWebRespMessage2Key = xpath(msgCreateSPServiceOrderAckResp.parameters,"string(" + strXPath + ")"); 


The one-step approach:


strCountMessageKeysXPath = ;

intCountMessageKeys =
// Yes you can put if statement in expression shapes (but not message assignment shapes) 
if (intCountMessageKeys >= 2) 
   strXPath = "//*[local-name()='MessageKey'][2]"; 
   strWebRespMessage2Key = xpath(msgCreateSPServiceOrderAckResp.parameters,"string(" + strXPath + ")"); 



NOTE: The reason I have .parameters after the message is that it is a multi-part message.
If you don’t get that correct, you may get the error “The expression you have entered is not valid”, or “An xpath expression must be of the form” if you hover over the error.


If you get the error “An xpath expression must be of the form …” (in an expression shape of a BizTalk orchestration), here’s one possible solution.

I was using a multi-part message, so instead of msgCreateSPServiceOrderAckResp, I had had to specify msgCreateSPServiceOrderAckResp.parameters.

The compiler just shows the error “The expression that you have entered is not valid”. But when you find the small red mark, and mouse over it, you see the following:

Here is the corrected version:




Today, I was tasked with upgrading an orchestration from calling one version of a web service (version 3), to a newer version 4.

Fortunately, it was backward compatible, i.e. I didn’t have to remap any fields. However, the schema was renamed, as it actually had the version number in the web service name. So how does one do this in BizTalk?

In this case, I’m sure there are many paths to the same destination, but here are the steps I followed.

1. I opened a new temporary Visual Studio BizTalk project and consumed the new web service (using the “Add Generated Items” / “Consume WCF Service”). The reason I did it in a separate new project is that it creates the dummy orchestration, and the binding files.

2. I then copied the 2 or 3 schema files to my actual project.

3. I checked my map out (from source control), and opened it in NotePad++ and had to do one small surgery. I had to find Reference Location=”..\WebServices\PlaceOrder_V3.xsd” and replace it with “..\WebServices\PlaceOrder_V4.xsd”. I could have tried it in map, but I’ve seen too many cases where you lose all your mappings, so I did it this way. I then opened the map to verify, and all looked good there.

I then removed the old web service schema, and did a Rebuild, just to see what would happen, which lead to the next two steps.

4. I had to reassociate my Multi-part Message types. Since the messages were using multi-part message types, they were okay as is. But I had two messages types (one for the web service request, and one for the response) that were “red” and had to change. So I just had to carefully pick the new .xsd name for each. (Could have done this also by editing the .odx file, if done carefully.)

5. If you had promoted (or distinguished fields) on the web service schema, you would have to redo those, and that was the case in this orchestration. Then, a really weird scenario happened. Every expression shape that was using the distinguished fields was getting an error. There was not red squiggly line under the items, just a compile error. Even closing and reopening Visual Studio did not solve it.

In one case, I re-typed the msg.property_name using Intellisense, and that solved the issue. For another shape, I did the same thing and it wouldn’t go away. I took a wild stab at it, and created a new expression shape, cut and pasted the statements from the old shape to the new shape, then it compiled clean. I cannot explain that part at all!

6. I’m about to change the URL in the SendPort now, and start testing. I’ll update if anything else unusual happens. I did not use the binding files created by the “Add Generated Items” in the first step above.

6a. Things went bad during testing, took me way too long, like 2 hours to get it working. I had to deploy to QA environment, because it was easier to test.
6b. One issue I had forgot was that the SOAP Action Headers needed to change (in the General configuration tab of the SendPort), for example:
<Operation Name=”PlaceOrder” Action=”” />
<Operation Name=”PlaceOrder” Action=”” />

6c. For some reason, it still didn’t work. I’m checking with the authors of the webservice if they change anything else. To finally get it to work, I had to take the CustomBindings.xml file, and run it on the QA system, then change my orchestration bindings to use the new SendPort.

While there can probably be many reasons for this error, here’s one that I had:

msgNew() = “”;

There was not value in the parentheses. For some reason, this does NOT put the red exclamation point on the Message Assignment shape.


I had been testing the following, then changed it, and forgot and left it blank

msgNew(BTS.OutboundTransportLocation) = “”;





One of the characteristics that separates the good from the great Biztalk developers and architects, is handling of errors, particularly SOAP errors.  This is often not tested sufficiently.

This blog by Shashidharan Krishnan does a good job of explaining how to catch a SOAP error in a BizTalk Orchestration:

I’d like to throw in some ideas that I implemented today.
Based on the blog above, I created the xpath below, a slightly simpler form to grab two of the main SOAP Fields. I only wanted the two most critical, in order to save space (I’ll discuss more about my column size limitations below). I didn’t want all the namespaces and SOAP wrappers, that just cluttered up any error that the user might see.

//SOAPEXECPTION_11 is my 'Exception Object Name' specified in the Catch (of the Scope) Properties 
strSoapFaultcode   = xpath(SOAPEXCEPTION_11, "string(//*[local-name()='faultcode'])");
strSoapFaultstring = xpath(SOAPEXCEPTION_11, "string(//*[local-name()='faultstring'])");

// format my own condensed error consisting of the above two parts 
strValue = "SoapFaultCode=" + strSoapFaultcode + " SoapFaultString=" + strSoapFaultstring; 

// Single quotes cause SQL to blow up, 
// truncate to 1000 (so we can put two fault codes in one DB field 
strValue = strValue.Replace("'","''");
vWebServiceAResponseMessage = strValue.Substring

The site where I’m working wanted to store the error back in a database table via a web service. Basically, the is a table that represents the canonical schema. A “poller” job extracts data from that table, writing a canonical XML to disk. An orchestration picks it up, and processes it. That same orchestration then calls a web services that was provided to me to update the same row of that table with the success or failure codes. If any webservice or SOAP errors are encountered, an flag is set, and that row can be re-queued to be be polled and processed again later after those errors have been fixed.

The database column for the error was a max of 2000 characters, and was not an XML column, just a varchar2(2000) column in an Oracle database. So if I passed to big of a field, the web service would blow up with a size issue on the SQL column. So it became my job to make sure my errors fit.

Now, to further complicate matters, imagine this scenario. I called WebService-A, then WebService-B. Each could have a SOAP error. Then I call WebService-C to actually update the table. So basically, I had to get a max of 1000 characters of error for each of the WebServices A and B, for a max of 2000. In some cases, you would not even call WebService-B if it were dependent on results from A; but in my case, they wanted to store the error from A into the backend ERP system (which is what WebService-B was updating).

So I was also dealing with a scenario where A could succeed and B could fail, A could fail and B could succeed, both could succeed or both could fail. I did this with just a normal decide shape with 4 or 5 branches. I set string variables there, then had one construct/message assignment afterward, using those string variables to construct the message request for WebService-C.

Further, if the SOAP message had single quotes in it, that was messing up SQL, so I had turn each single quote into two single quotes. (If you are not familiar with this, the classic case is LastName = O’Brian needs to be treated as O”Brian. Typcially, the database server is set up to handle to consecutive single quotes as one single quote, and helps avoid confusion with the single quotes used in the SQL syntax.

Here are two other thoughts to consider. Should your orchestration be flexible enough to handle SOAP 1.1 and SOAP 1.2 errors? I usually don’t go that far, but the guy I worked with did. It’s nice and flexible, but causes a little extra bloat in the orchestration.

For the final thought, there can be “hard” SOAP errors, or soft business/errors. At this client, the web service typically return a Result that was either set to “Ok” or some error. So in addition to checking the SOAP errors, I had to check that error as well. This is fairly typical.

In other orchestrations that I’ve recently written, I created a common error handler, then threw an internal exception or set an “IsError” variable/flag, so that the common error handler could run once as needed. That way, I could treat SOAP 1.1, SOAP 1.2, or soft/business errors using the same logic. Orchestrations don’t allow easily for re-useable code. You either have to call a sub-orchestration, use direct-binding to call another orchestration, call C# code, or try to create a code block that runs based on flags. Having separate orchestrations can make restart a big pain.

And what do you do when your exception handling webservice itself has an error?  I’ll leave that for you and your architect.  Here, we “pretty print” all XML request/responses that have errors, and email them to a distribution group.

How to cause a SOAP error to Test a BizTalk Orchestration

Changing the URL didn’t do it, that caused an XLANG/s exception, with a service not found exception, as shown below:

Error Description: System.ServiceModel.EndpointNotFoundException: There was no endpoint listening at that could accept the message. This is often caused by an incorrect address or SOAP action. See InnerException, if present, for more 


In the real world, an error like this would be fixed by changing the URL and resuming the orchestration.

One thing I do to force a SOAP exception is to edit the WCF SendPort, and modify the “Action” block on the General tab. I save the original values to NotePad++, then remove or change the values of the: <Operation Name=”value”…
You may have to restart the host instance, then run the test.

This results in the following error:

  The message with Action '&lt;BtsActionMapping xmlns:xsi="" xmlns:xsd=""&gt;
  &lt;Operation Name="MyMethod" Action="" /&gt;
&lt;/BtsActionMapping&gt;' cannot be processed at the receiver, due to a ContractFilter mismatch at the EndpointDispatcher. This may be because of either a contract mismatch (mismatched Actions between sender and receiver) or a binding/security mismatch between the sender and the receiver.  Check that sender and receiver have the same contract and the same binding (including security requirements, e.g. Message, Transport, None).

When you are done testing your exceptions, then copy back what you saved in NotePad++.

If you happen to be the author of the webservice (or the author is inclined to work closely with you), you might want to code in a web service exception that will be sent back as SOAP exception. Use some flag or freaky/sneaky set of values to trigger the exception (make sure those values would never occur in the real production environment).

I had this case again today, where I got “Root element is missing”. The code was working, I made some changes, and boom, an existing code path started blowing up. It was actually a trace routine, where I had the following code:

   xmlDoc = msgWhatever;
   //then I passed as a parameter:  

So here is the code I added, above the section that bombed:

   // Avoid compile erorr "Use of unconstructed message 'msgCanonicalErr'
   // in the common error handler after the end of the big Decide Block
   xmlDoc.LoadXml("<Dummy />");
   msgCanonicalErr = xmlDoc;

The simple fix was to create another xmlDoc variable with another name:

   // Avoid compile erorr "Use of unconstructed message 'msgCanonicalErr'
   // in the common error handler after the end of the big Decide Block
   xmlDocInitializer.LoadXml("&lt;Dummy /&gt;");
   msgCanonicalErr = xmlDocInitializer;

I think another solution would have been to reset the xmlDocument variable, but I preferred the above approach:

   xmlDoc = new System.XmlDocument(); 

We all hate to use Atomic Scopes in BizTalk orchestrations when not needed.  I have a static C# Trace routine that normally takes passing an enum of System.Diagnostics.TraceLevel (for Error, Warning, Info, etc…).   In the current project, our web services can return “soft errors” in a common field called “Result”.

So I could have used a Decide shape, but since the code repeats on many webservices, I wanted to us an if/else statement in an expression shape called “GetResults” (in picture below).

if (msgResponse.RESULT == "Ok")
     vTraceLevel = System.Diagnostics.TraceLevel.Info;
     vTraceLevel = System.Diagnostics.TraceLevel.Error;
if (msgResponse.RESULT != "Ok")
  strSoapFaultMessage = "2510:msgResponse:" + msgResponse.Message;
  throw new System.ApplicationException(strSoapFaultMessage); 

The reason I coded like this is that I had a large orchestration with about 8 web service calls, and I wanted a common error handler for all of them. That Catches a System.ApplicationException, writes to EventLog, and sends an email with the full Request and Response XML of the call/response to/from the web service.

Now all this happens to be in a debatching loop. When I ran it, and had multiple errors, the first one had a blank response in the email, and the second and third ones worked. It seems very inconsistent, but here’s what a colleague and I figured out.

In the picture below, my original shapes are on the left, and the revision is on the right. Scope_C_NonSerializable_TraceLevel was an Atomic Transaction to support the fact that TraceLevel was non-serializeable. So if the orchestration blows up in this Scope, it would have to restart at the beginning of the scope.

My mistake was to include the “Throw” in that scope. Apparently the “Throw” sometimes acts as sort of a Rollback, and clears some or all variables set in that Scope.

In the shape called “TRC 2510”, I had the following, along with a call to my C# trace routine.

xmlDocResp = msgAsurionOrderRoutingResponse; 

So when the Throw happens, at least on the first time through the loop, the xmlDocResp had no value. Simply moving the “Throw” and “Trc 2511” outside the loop seemed to solve the issue.


The Catch you see above is the Captch of the BTS.soap_envelope_1__1.Fault.  It also sets xmlDocResp to the value of the SoapFault, and throws an ApplicationExcpetion so that same error handler can work for both Soap Faults and the “soft” web service errors.

The common error handling had the following in a message assignment shape:

tempStrBuilder.AppendLine("Request Message:");
tempStrBuilder.AppendLine("Response Message:");

I’m considering adding a C# formatter to do a “pretty print” on the XML (done) to make the error email look even nicer, probably based on the code on this Stackoverflow page.