Posts Tagged ‘Orchestration’

Today I want to talk about a very common problem that can occur when we are invoking BizTalk Orchestrations exposed as a synchronous services (Request-Response Receive ports):

"System.Net.WebException: The operation has timed out"


In my case I was trying to invoke an orchestration exposed as a WCF service. And of course this can be very straightforward problem, most of the times easy to detect and probably also to fix… but sometimes BizTalk tries to play with us and throw a few good surprises…


Typically this problem is usually associated with network problems or lack of Error Handling inside Orchestrations:

  • You are trying to invoke an external system inside the orchestration and it take too much time to respond and naturally we get a time out error.
    • The SOAP.ClientConnectionTimeout property can be used on a Web service that take a long time to return a response to try to solve or address this problem. See more here.
  • You can have a High Volume of request and you can overload the external service with too many concurrent calls or you can have limits of max connections to a certain address and will naturally this can cause affect the performance and provably will take too much time to respond.
  • This error can also occur when the BizTalk performance get degraded and it start responding slow. If the BizTalk jobs are not well configured and running the size of BizTalk Databases can grow extremely and responding very slow and we get stuck with this error.
    • You need to validate the jobs and the database and if necessary you need to configure the jobs and clean the databases with the Terminator tool and provably shrinking also the databases to resolve the problem.
  • Also you can get this error because you don’t want to handler errors inside orchestrations, so for example if you don’t handler WCF Fault messages from your external service or you are invoking a C# code and it raise an exception, and you are note handling this situations in your orchestration, the orchestration will be suspended an you will get a timed out exception.
Nothing fit in the problem. What can it be?

But … and when all this is checked and doesn’t fit in the problem that is happening. What can it be? Before explain let me describe my scenario:

  • I have a simple demo service that receive a small message, invoke an external service and return the message to the source system.
  • Because of API limitation I decide to invoke this external services with C# and control Exception inside orchestrations.
  • I know by using HAT and debugging in DEV environment that the external service was giving me a known error that I was controlling and throwing the error in order to create a response with the error description, inside the orchestration, to be returned to the original system.

So nothing to fancy and very simple stuff. However every time I tried to test the orchestration the orchestration was stuck in the message box in suspended state… the external service was invoked, the error was catch in the code, logged and the exception was raised for the orchestration and after that nothing … the engine seemed unaware and did not understand what was happening, crazy I know.


When I investigated the Event Viewer to try to find more information I found this description:

xlang/s engine event log entry: Uncaught exception (see the ‘inner exception’ below) has suspended an instance of service ‘MyOrchestration(728766c9-9df2-609b-004e-fa2e7c3079c4)’.
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: 4dfd6041-d52f-4110-8d0d-92efc48f0c38
Shape name: InvokeExternalService Shape
ShapeId: eff276fd-f289-4778-ba47-ff66309ae8c6
Exception thrown from: segment 2, progress 8
Inner exception: Fault Response: My Error Description

The first thing I thought was that I incorrectly published some resource (DLL) … but after validating and publishing the solution again, the problem prevailed.


The Orchestration Designer can play some tricks to developers. And be very careful when you copy shapes from one orchestration to others!

What I did was open a similar solution and copy the main scope (body of the orchestration) to a new solution that I had created. This will also copy all the shapes inside the scope… and of course I change the shapes to fit my new requirements, by deleting some shapes and change the code inside others… Why? To be faster and not lose much time creating the main sketch of the orchestration.

But be aware that the Orchestration design don’t like some of this operations (for me it’s a bug inside Orchestration design), and for some reason the designer doesn’t interpret well the shapes (“refactoring” or the “graphical interpretation”). He compile when the solution but in runtime we get stuck with the error “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.”

I don’t know if some also detect this behavior before but I already experience this twice.


To solve this strange behavior you need to redesign the same Orchestration flow by:

  • Dragging new shapes to the Orchestration design and copy the exact same code inside the existing shapes to the new ones… you can also give the same names!
  • At the end delete the existing shapes (which had been copied).
  • Compile and deploy the project again.

Without doing anything more this solved my problem.

In the past I developer a demo on “How to Call Orchestration from another project or from another BizTalk Application” that you can read here and download the source code from Code Gallery here.

This demo was compose by one Visual Studio Solution with two different projects:

  • Project1
    • Orch1
    • Schema1
  • Project2
    • Orch2

However there were a few questions about how we can accomplished that using two different solutions… well is the exact same process, but to help clarify this topic and to better help the community members that placed the questions I decide to create a different demo.

In this demo we will create two Visual Studio Solution:

  • CallExternalOrchestrationCommonSolution with a common orchestration that will be called from others orchestrations
    • This will be deployed to a BizTalk Application called “CallExternalOrchestration.Common
  • CallExternalOrchestrationMainSolution with a main Orchestration that will call the common Orchestration using the “Call Orchestration” shape.
    • This will be deployed to a BizTalk Application called “CallExternalOrchestration

In both of the solution I will describe the basic steeps (or the most important steeps) to accomplished

Creating the Common Solution: CallExternalOrchestrationCommonSolution

This project contain an orchestration that will receive two input string (however you can define other types of input like message or other types) and will construct a message that will be sent to folder on the file system.


Again, I will not explain all the steps to create the entire flow of the orchestration. The most important thing here is to define the “Type Modifier” property of the orchestration.

If we make an analogy with C#, we can say that this property is the same as the Accessibility Levels to C# members or types. The “Type Modifier” property defines the scope of an Orchestration, i.e., it indicates the access restrictions to this Orchestration. An Orchestration can be public, private, or internal.

  • If it is Public, it is visible to anyone interacting with the orchestration.
  • If it is Private, it is visible to other orchestrations within the same project and namespace.
  • If it is Internal, the port type is visible only within the project.

When we create an Orchestration, the default “Type Modifier” is “Internal”. So to be able to call this orchestration from a different Visual Studio Solution or different project we need to set the “Type Modifier” to “Public”.

To set the “Type Modifier” property for an orchestration to “Public” you need to:

  • Open the orchestration in Microsoft Visual Studio
  • Right-click somewhere in the orchestration designer (except in the shapes otherwise you will go to the shape properties), for example the green start shape at the top of the orchestration and select the “Properties Windows” option to display the Orchestration Properties dialog


  • Set the “Type Modifier” property to Public as you see in the picture.

Compile and deploy the solution.

Creating the Main Solution: CallExternalOrchestrationMainSolution

The second project, basically contains one orchestration that will receive an input message from a folder on the file system and will call a common (or external) orchestration.


Again, I will not explain all the steps to create the entire flow of the orchestration. The most important thing here is to import the reference (DLL) that contain the common orchestration that we want to call.

To import the reference to your project you need to:

  • In Solution Explorer, right-click in “References” and select “Add Reference”.
  • In the “Add Reference” dialog box, select the “Browse” tab that enables you to browse for a component in the file system.
  • Select the components you want to reference, and then click OK.
    • You can select multiple components by holding down the CTRL key, provided the components are all on the same tab.

Now if you drag a “Call Orchestration” shape to your orchestration you will be able to select the common orchestration that we create earlier, as you can see in the picture bellow:


Once again, compile and deploy the solution.

Download the sample:

How to Call Orchestrations developed in a different Visual Studio Solution (206.2 KB)
Microsoft | MSDN Code Gallery

When you compile your BizTalk project, you receive the error:

"you must specify at least one already-initialized correlation set for a non-activation receive that is on a non-selfcorrelating port".


This is a very basic mistake, and usually occurs due to developer forgetfulness.


This error can occur if your orchestration has no activating Receive shapes (Activate = true) or has no activating Receive shapes and is not called directly by another orchestration.


If your orchestration is not called by another orchestration, you must configure one of the Receive shapes to be an activated receive. For more information about configuring the Receive shape, including links to correlation, see How to Configure the Receive Shape.


Tags: BizTalk | Orchestration | Errors and Warnings, Causes and Solutions

When trying to help a friend of mine configuring a dynamic SOAP Adapter Solicit-Response port, some like this:

WSSAPCreatePO_Send(SOAP.ClientConnectionTimeout) = 300000;
WSSAPCreatePO_Send(BTS.RetryCount) = 3;
WSSAPCreatePO_Send(BTS.RetryInterval) = 15000;

We got this strange error when trying to compile the project:

“identifier ‘RetryCount’ does not exist in ‘myprojectnamespace’; are you missing an assembly“

My friend actually found what was the problem and keep me track of the solution (for that thank you) that I found it quite interesting to share with you all.


This problem occurred because the namespace of the solution that was used was something like this:

  • ‘CompanyName.Project.Module.BTS.

This problem occurs because we used a special keyword in the namespace used by BizTalk: “BTS” and when we try to compile the project the compiler is trying to get the property RetryCount from the namespace of the BizTalk project: ‘CompanyName.Project.Module.BTS‘ instead of namespace BTS associated with Microsoft.BizTalk.GlobalPropertySchemas assembly



To solve this problem just rename the namespace of your project, eg:

  • ‘CompanyName.Project.Module’
  • ‘CompanyName.Project.Module.Bts’

I don’t recommend the last one J and I suggest you never use special keywords in your project namespaces.

See BizTalk: Naming Convention for BizTalk Solutions by Leonid Ganeline

Tags: BizTalk | Orchestration | Errors and Warnings, Causes and Solutions

It’s very common to use .NET code for orchestration support and also to log errors, warnings or information in Event Viewer. I have as a principle, not to register this type of information on Application Event Log. For me this log is to be use by system applications like BizTalk, SharePoint and others, so if we register all custom information in this log, we can infest the log with unnecessary information and lose or difficult the visualization of important information. I advise the creation of one or more custom logs and for that I use this code:

if (!System.Diagnostics.EventLog.SourceExists(sourceName))
   System.Diagnostics.EventLog.CreateEventSource(sourceName, logName);
System.Diagnostics.EventLog.WriteEntry(sourceName, genericString.ToString(), logType);

However when I installed one BizTalk Application in a brand new environment I caught this error:

xlang/s engine event log entry: Uncaught exception (see the ‘inner exception’ below) has suspended an instance of service ‘My.Orchestrations.Orch(f0b8a3ff-15cd-03db-2c20-4530bda13468)’.
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: a69409e2-094c-4f5b-9dd6-f448eec3bd3c
Shape name: Response Error Construct Msg
ShapeId: 95ffeaaa-dd23-4c09-8e3e-7fcd07342a11
Exception thrown from: segment 3, progress 3
Inner exception: The source was not found, but some or all event logs could not be searched. Inaccessible logs: Security.

Another typical error is: You receive the “Requested registry access is not allowed” error message when you try to create a custom event log


This problem occurs because the user account that you used to log on does not have sufficient permissions.
The first time that you call the EventLog.CreateEventSource() method to create a custom event log, the custom event log entry is created under the following registry subkey:

  • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog

To create this subkey entry, you must have permission to write. However, the regular user account does not have permission to write.

So, the user that runs the application must have administrative rights to create a new event log source or a new custom log.


You need to grant permission to create a custom event log:

  • Log on to the computer as an administrator.
  • Click Start, click Run, type regedit in the Open box, and then click OK. The Registry Editor window appears.
  • Locate the following registry subkey:
    • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog
  • Right-click Eventlog, and then click Permissions. The Permissions for Eventlog dialog box appears.


  • Click Add, add the user account or group that you want and set the following permissions: “Full Control”


Tags: BizTalk | Orchestration | Errors and Warnings, Causes and Solutions

For some reason after having migrated a BizTalk 2006/Visual Studio 2005 solution to BizTalk 2010/VS 2010 using VS Conversion Wizard, I got the following error:

"Errors exist for one or more children."

Following for another saying he did not recognize certain message, which honestly was a little strange, I should have a total about 20 “false” errors Sorriso.


Typically this problem is usually associated with problems in Orchestration Designer “refactoring” or “graphical interpretation” and in a certain way it isn’t a “valid error”, ie, it doesn’t describe the real problem.

Usually this error is followed with a red indicator on the shape; however this was not my case, I had no indicator, but had the same error.


If you have a shape indicator, enter in the shape:

  • Copy and delete the existing code and press ok to leave the shape;
  • Go back to the shape again and put the same code there;
  • Compile the project again;

In my case, I did the same strategy on the first shape where I had code (Message Assignment) that referenced the message that he said that did not recognize.

Tags: BizTalk | Orchestration | Visual Studio |Errors and Warnings, Causes and Solutions

It’s very common to use .NET code for orchestration support. In one of these scenarios I decide to use a class for, in a certain way, validate request and add more information, and to my surprise I was blessed by this error:

An unhandled exception (‘<System.StackOverflowException>’) occurred in BTSNTSvc.exe [2756]. Just-In-Time debugging this exception failed with the following error: Debugger could not be started because no user is logged on.
Check the documentation index for ‘Just-in-time debugging, errors’ for more information.


And to further aggravate the situation my Host Instance associated to the process stopped. First action was to reactive the host instance! But for my surprise again! Automatically the host instance stopped again! Sorriso


First, let put some integration context…


My team requested me, ASAP (this would be one of the problems Sorriso), to develop a method to change User Contact Information across different platforms. Basically, I get a request with different attributes, each of them is optional and so I need:

  • First to read the user contact information from my “Cache” DB
  • See the fields that aren’t filled, and filled them with the cache information
  • Update the user information across different platforms
  • Update my database user information


So to accomplish that goal, I decide to create a Serializable public class UserProfile and use this class as a variable inside the orchestration



First clue:

  • A StackOverflowException exception is thrown when the execution stack overflows by having too many nested method calls.
  • Tips: Make sure you do not have an infinite loop or infinite recursion.

Second clue:

  • Because I was running different processes in that host instance, I had to validate which process was causing the error
  • When I found the process, I found that no orchestration artifact is load, so the problem was in the Initialization of the artifact, but I cannot find an easy way to debug from Visual Studio.


It happens to everyone… I usually say that these kinds of problems are between the chair and the keyboard Sorriso.

The cause of the problem was in the definition of a variable of class UserProfile, I put in the return the name of the prop snippet instead of the variable, and this cause an infinite loop.

private string userFirstName = string.Empty;
/// <summary>
/// User First and Last Name
/// </summary>
public string UserFirstName
      return UserFirstName;
      userFirstName = value;


Easy, rectify the code.

The major difficulty in this scenario was how to find the error. I was able to debug the .NET stack using the Microsoft Symbol Server to obtain debug symbol files ( that I will explain a little more in one of my next posts.


  • ASAP never works well Sorriso
  • Be aware with copy –> paste

Last but not least, I want to thank Jorge Lourenço for help, which is one of the best technicians that I know in regard to detecting and solving problems

Tags: BizTalk | Orchestration | Errors and Warnings, Causes and Solutions


I have one scenario that at the end of the orchestration I will delivery notification to the client, one branch will send notification by SMS, another by email but both branches make user of one orchestration variable: UserProperties.


When using parallel shape inside orchestration that makes uses of a given orchestration variable, you can get a compiler error:

varName‘: if shared data is updated in a parallel then all references in every task must be in a synchronized or atomic scope


To solve this error you have to options:

Solution 1:

If you want to use translations inside the branches you need to:

  • Open Scope Properties of each branch
  • Set “Synchronized” property to “True”


Solution 2:

If you don’t need to use translations inside the branches!!

  • Just set “Transaction Type” property to “None”

Tags: BizTalk | Orchestration | Errors and Warnings, Causes and Solutions

Handling exceptions inside orchestration is the equivalent of doing a “catch { }” block in C#, of course there are some little differences, but the idea is the same.

General Exception Type

When we create New Exception Handler, in property “Exception Object Type combo, the only item in the list is ‘General Exception’:

Think of catching a “Generic Exception” as the equivalent of doing a “catch { }” block in C# with no exception declared. “General Exception” allows BizTalk to deal with any exception it may catch and re-throw, there’s no way to get the exception message at that point.

How can I get Exception Message

You can accomplish this by change the exception type to System.Exception or other type (System.Web.Services.Protocols.SoapException):

  • In “Exception Object Type” property select: <.NET Exception…>
  • In Artifact Type windows, select System.Exception

By selecting another type, you are able to define “Exception Object Name”, in this case “ex”, and then for getting the error message is just like C#: “ex.Message” or “ex.ToString()”.

Handling Delivery Failure Exception (using a request-response port)

There is a great post by Naveen Karamchetti about this; this is the key steps…

In order to catch an exception within your scope block in BizTalk while using a request-response port, you might have to do the following:

  • Set the retry-count to 0 on your physical request-response port which you use to bind.
  • Enable the flag Delivery Notification to ‘Transmitted’ on your logical request-response port within the orchestration.
  • Catch the “Microsoft.XLANGs.BaseTypes.DeliveryFailureException” exception and handle it as you’re please.

The Delivery Notification flag on the Send Port indicates that the orchestration must be NOTIFIED back, in case the message has not been received by the destination. Delivery Notification works only when the Retry Count set to 0. When a message cannot be delivered, a Delivery Failure Exception is raised and the exception needs to be handled by the Orchestration.

Handling and Throwing SOAP Exceptions from BizTalk

Similar to Delivery Failure, but in this case, we have to configure the Exception with “System.Web.Services.Protocols.SoapException”.

Note: remember to set the retry-count to 0.

To get error message, just: “ex.Detail.InnerText”

Download the example source code:

Handling Exceptions inside BizTalk Orchestrations (88.9 KB)
Microsoft | MSDN Code Gallery


Tags: BizTalk | Orchestration | Exceptions | Training

There are 3 ways that we can read and set values of the message inside orchestration:

  • Using Property promotion
  • Using XPath expressions
  • Using C#/VB.NET object (serialization)

The last one is the most uncommon but it can be done, serializing the message into object.

Using Property promotion

Property promotion is about getting easy and fast access to data.

  • Easy: Because you typically do not have to know anything about your data to get access to it. Rather than some long XPath query with possible errors.
  • Fast: Because you do not have to load the whole message into memory to get access to the data. It is placed inside the message context (a collection of key-value pairs that are associated with a message).

BizTalk provides two different types of promoted properties based on what you want to do with the data. The two types are:

  • Promoted Properties: are system wide.
  • Distinguished Fields: are light weight and only accessible inside an Orchestration.

They are read/write so it provides an easy way to change values inside your message without using a map – such as updating a status field.

Learn more: Distinguished Fields vs. Promoted Properties, Basics of Promoted Properties

Using Promoted Properties:

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName)), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
msgOutput1(AccessingAndChangeMessageValuesInOrchestration.PropertySchema.FirstName) = "Sandro";

Using Distinguished Fields

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(msgOutput2.LastName), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
msgOutput2.LastName = "Pereira";

Using XPath expressions

Working with XPath inside Orchestrations is a powerful and simple feature of BizTalk. XPath can be used to both read values and set values inside your Message. To set values in your message, you need to be inside a Message Construct shape.

XPath queries can only be done against a Message – can also be executed against untyped messages (that is, a Message that is of type System.Xml.XmlDocument) – and the results can be set to a Message, XML Document or other orchestration variables.

Learn more: XPath 1.0 Function Library Quick Reference, Operators and Special Characters Quick Reference

To see what is the XPath expression of the field:

  • Go to schema and select the field that you want
  • Right-click and select “Properties”
  • Select the value of the property “Instance XPath”

Using XPath Expression in Message Assign:

System.Diagnostics.EventLog.WriteEntry("Orchestration", System.Convert.ToString(xpath(msgOutput3,"string(/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()=''])")), System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
xpath(msgOutput3,"/*[local-name()='Person' and namespace-uri()='http://AccessingAndChangeMessageValuesInOrchestration.Schema1']/*[local-name()='Age' and namespace-uri()='']") = "00";

Using C#/VB.NET object (serialization)

BizTalk able to automatically convert message in C# object and C# object into BizTalk message.

To accomplish this we have to generate C#/VB.NET classes based on Schemas using XSD.EXE, or those of you not familiar with XSD.EXE it’s a command line tool shipped with Visual Studio .NET that allows you to generate Classes or Typed DataSets based on XML Schemas, normally you might try to write code to create a XML Document (based on a schema), you end up writing pages and pages of painful code to construct a XML document by using the DOM (XmlDocument).

How to create class from schema:

  • Start Menu -> All Programs -> Microsoft Visual Studio … -> Visual Studio Tools -> Visual Studio … Command Prompt
  • Go to the Schema folder and type “xsd /classes /language:CS Schema1.xsd”

Create Orchestration variable

  • First you have to create an orchestration variable from the class that you create previous
  • On property Type select <.NET Class…> and select Person class that you create previous

Using C# object inside Message Assign

varPersonMsg = msgInput;

System.Diagnostics.EventLog.WriteEntry("Orchestration", varPersonMsg.FirstName + " " + varPersonMsg.LastName, System.Diagnostics.EventLogEntryType.Error);

//SET (Write)
varPersonMsg.FirstName = "Sandro";
varPersonMsg.LastName = "Pereira";
varPersonMsg.Age = "00";

msgOutput4 = varPersonMsg;

Download the sample source code:

You can download the example source code (zip file) at here.

BizTalk: Accessing and change message values inside orchestration (242.2 KB)
Microsoft | MSDN Code Gallery

: BizTalk | Orchestration | Messaging | Training