Have you been looking for how to find the string text specified in the BizTalk Terminate Shape?  I hadn’t used this shape in a long long time, and had to check it out again this week.  This blog show you you where the Terminate Shape text goes.

After your orchestration has hit a Terminate statement, you can do the following two steps:

1. In BizTalk Admin, go to the group hub, and click on “Terminated Instances”.


2. Find the terminated instance of your orchestration.


The text does NOT appear in the application EventLog. You would have to do a System.Diagnostics.Write.EventLog in an “Expression Shape” to do that.

For example:


The orchestration is terminated, not suspended, so there is nothing to be seen in the “Suspended” query.

In this blog by Yossi Dahan, he talks about how there should perhaps be an “End” shape that doesn’t imply a termination/error.

By the way, even thow there is a “Throw” shape in BizTalk Orchestrations, there’s nothing to stop you from doing a .NET “Throw” in an “Expression Shape”, for example:

if (vCO_HeaderUpdateResult != "Ok")
strSoapFaultMessage = "2240:msgCO_Header_Update_Response:" + vCO_HeaderUpdateMessage;
throw new System.ApplicationException(strSoapFaultMessage);

In the program above, I caught a “soft error”, i.e. the I called a web service that completed without a hard Soap error, but it set an error in the variables that it returned. Thus, I raised an error via the “Throw” keyword, then caught the error in the Exception Handler of a scope. This allowed me to have one common error handling routine for the 10 different web services that I was calling in the one orchestration. That common routine wrote to the EventLog, Sends and Email via an email send port, writes to a Trace, and then does ends the orchestration, probably via the Terminate statement (still need to discuss with my colleagues).

I got this error today in a BizTalk orchestration: “Identifier “abc” does not exist in ‘global_NS.AppName”; are you missing an assembly reference?” Basically, the auto-complete (Intellisense) wasn’t giving my .BizTalkComponents namespace after I typed in “AppName.”. So I typed it in anyway, and pressed CNTL-Space-Bar, and that’s when the error occured.

I had typed in AppName.BizTalkComponents, which was a valid namespace in C# program, to which I had made a project reference.

Normally, I follow naming conventions that match the BizTalk Deployment Framework, but in this case, I has an old application, written by a predecessor. I use a Find/Replace Utility to replace the namespace from NewAppname to Appname.
So, the namespace of the orchestration itself was Appname. I should have named it Appname.BizTalk or something similar.

So to fix the issue, I overrode the namespace of the orchestration to Appname to Appname.BizTalk (as shown below):


Was getting this error

xlang/s engine event log entry: Uncaught exception (see the 'inner exception' below) has suspended an instance of service 'MyProjectName.MyOrchName(8f69ac91-51ae-67be-b342-b3ee431859ca)'.
The service instance will remain suspended until administratively resumed or terminated.
If resumed the instance will continue from its last persisted state and may re-throw the same unexpected exception.
InstanceId: a38b30ab-455a-479e-8015-ac6d6960b5e9
Shape name: MyMessageAssignmentShape1
ShapeId: 426c4c2f-d3b1-4903-b4f3-648b275f899a
Exception thrown from: segment 2, progress 9
Inner exception: Object reference not set to an instance of an object.

Exception type: NullReferenceException
Source: MyOrchName
Target Site: Microsoft.XLANGs.Core.StopConditions segment2(Microsoft.XLANGs.Core.StopConditions)
The following is a stack trace that identifies the location where the exception occured

at MyProjectName.MyOrchName.segment2(StopConditions stopOn)
at Microsoft.XLANGs.Core.SegmentScheduler.RunASegment(Segment s, StopConditions stopCond, Exception& exp)


I added a lot of trace/diagnostic statements and found it was blowing on this line of code, which was in a message assignment:

vXmlDocMsgToProcess = msgCanonical;

I simply added a “New” statement on XmlDocument to recreate the object/reference. Not sure 100% why it was required, but it made BizTalk happy. I seem to remember from years back when I was doing a lot of loops, that it’s often a good idea to reset your XmlDocument when in loops.

vXmlDocMsgToProcess = new System.Xml.XmlDocument();
vXmlDocMsgToProcess = msgCanonical;


This worked fine, but only for a while. When I removed some trace statement later, the exact same error came back in the exact same place.

2. The last thing I did, was to create a new variable: vXmlDocMsgToProcess2 and replaced the variable above.
So far, it is working.

I think this is a Microsoft bug, not sure if my machine has all the patches and cumulative updates on it.

3. A co-worker recommeneding doing the “new System.Xml.XmlDocument()” one time before the loop. Said it solved his similar issue.

How do you use the XPath statement on the left side of an assignment statement (i.e.. the left side of an equation or the equal sign)?  I’m referring to a message assignment shape, in an orchestration, where you want

This is the MSDN page for the BizTalk XPath statement.  There are two problems with that page.

1) Xpath subscripts ared 1-based and not 0-based. See http://stackoverflow.com/questions/3319341/why-do-indexes-in-xpath-start-with-1-and-not-0.
Seems like that page might have a mistake, is says “select the fourth book element”, but shows xpath of “/catalog/book[3]”.
2) It doesn’t show a good example of how to set an XML element value.

The “String” function, is used only the right side of the assignment statement. It is used to convert a “node” to a string value.
You can copy/paste the XPATH from the properties box on a schema or map (after clicking on the element or attribute).
I like to put the xpath in a string variable. I then had to add the subscript, which is needed if you have an element that has “Max Occurs=UNBOUNDED”.
In this case, I only had one MESSAGE_HEADER child, but I still had to specify the subscript of [1].

//NOTE: Substring [0] after MessageHeader
strXPATH = "/*[local-name()='MyRoot' and namespace-uri()='']/*[local-name()='MESSAGE' and namespace-uri()='']/*[local-name()='MESSAGE_HEADER' and namespace-uri()=''][1]/*[local-name()='FILE_NAME' and namespace-uri()='']/text()";
xpath(msgCanonical, strXPATH) = strFileRcvdName;

Note the following;

1) If you leave off the /text() statement, you might get this error:
“selected a node which is not valid for property or distinguished field retrieval, or it selected no node at all. Only text-only elements or attributes may be selected”.

Other errors related to bad Xpath:

Inner exception: Expression must evaluate to a node-set” – I think this happens if you put the String statement on the left side of the assignment statement.

NOTE: A few months after writing this post, I copied the above into a different message assignment shape, and got this error:
Inner exception: Illegal attempt to update the value of part ‘part’ in XLANG/s message ‘msgCanonical’ after the message construction was complete.
The issue was that in that orchestration, the message name should have been msgCanonicalCombined, as that was the message being constructed. It turns out I also had a msgCanonical in the same orchestration. Thus, the errors was subtly telling me that msgCanonical cannot be changed; I need to build a new message. Well, that is what I was doing; I just made a copy/paste typo. Changing to “xpath(msgCanonicalCombined, strXPATH) = strFileRcvdName;” fixed the error.

Every once in a while, I need to write to the Application EventLog from a BizTalk Orchestration, although I usually have my own SQL trace that I write to.

On almost all the overrides for WriteEntry, the first parameter is “Source”. I suggest you try some existing source, such as “XLANG/s” or “BizTalk Server”. You can create your own source, but then if you are not running in Admin mode, and you are the first person to write with that source, you will die with an error. (See separate section on that further below.)

Sample Code in an Orchestration Expression Shape

    "eSecuritel SSO Issue: " + exSOS.ToString(), 

I used the above in a “Catch Exception” within a scope.
You can see the other overrides here , but the one above with three parms seems to be the most common.

By the way, I got too fast typing, and actually put in System.Diagnostics.TraceEventType.Warning. The Trace has the shares some levels that the EventLogEntryType has (Severe, Error, Warning, Info), but has more options. Needless to say, I had the red-squiggly line under some code, and of course it wouldn’t build because of a signature mismatch.

Creating your Own Event Source

This must be done in advance by an administrator. There is a windows command that will do it for you, either run it from the command prompt, or put it in a .cmd/.bat file:


or if you prefer PowerShell, do something like this:

Write-EventLog -LogName Application -Source "MyNewSource" -Message "My first log" -EventId 0 -EntryType information

One trick to remember is that if you do this on your test system, you will have to remember to do it when you deploy up to the next higher environment (e.g. QA, UAT, or Production).


The document specification <ddlname.schemaName+SchemaRootNode> from assembly <etc…> failed to load.  Verify the schema for this document specification is deployed and is in the Global Assembly Cache.


In our case, this happened when we ran a C# client tester program that called an orchestration published as a WCF service.  The Application Pool was not configured correctly, and had .NET v2 instead of .NET v4.  Thus it was looking in the “old GAC”, rather than the new one.  The schema was truly deployed and GAC’ed.  We just changed the app pool and restarted it.


March 29, 2011 Orchestration Issue

If you get this mysterious error in a BizTalk orchestration:

Value cannot be null. Parameter name: val 

If you are running an orchestration, then a potential problem is that you tried to set a “distinguished field” to the value of NULL.

How I hit this error today ? I had a config parm from the BTNTSVC.exe.config file, that the orchestation was using to set the distinguished field. I thought the parm was optional, so I removed it from the config file. Then “BOOM” – the orchestration that had been working for months quit working with the “mystery error” above.

So now, I check for the config parm, and if it’s null, I reset it to an empty string.

May 17, 2017 Pipeline C# ReplaceString Issue

Value cannot be null. Parameter name: oldValue

Today, this happened in a pipeline component. Due to a logic error, a field had a value of Null, and it was being passed to a C# ReplaceString function as the “oldValue”. The oldValue parm can be an empty string, but it cannot be null.