BizTalk: Handling Custom Exceptions in Orchestrations

Hi Folks,

Sometimes in Orchestrations you would like to throw a custom exception. Before we begin, remember this rule:

  • Never throw a general exception outside the catch block in an Orchestration

The rule above is a bit funny, because when you drag a default exception shape in a try block within an orchestration, it will default to General Exception and you cannot choose any other exception type.

Imagine we need to call a web service and then handle the response from it within an orchestration. However, sometimes I may get a timeout from the web service or I would only like to wait a 1 minute or so to get the response. What I usually do in these cases is create a listen shape after I have called the web service and then I use a delay shape to wait a specified amount of time for the web service response, if it does not respond within the time span , I simple throw a Timeout Exception.


However, as mentioned when you drag a default throw shape, the only option is to throw a general exception, to solve the problem, create a variable of type .NET Class

Then, navigate to the mscrolib library:

And choose the exception type as illustrated below.

Give the variable a friendly name in the Orchestration View

Add a throw exception under the Delay shape and assign the type of exception to the variable name you created (Weird I know, but this is how it is done)

Below are the properties of the Throw Exception Shape

As you can see above, I have a listen shape after sending a message to a web service and am now waiting for a response.

And you nearly done, what you then do is add a Catch Exception by right clicking the scope and clicking add exception handler:

  • Remember all transaction should be in a scope, so your catch blocks will automatically be appended to it. Now it is time to customize the catch block.

Right click the new Catch Block and set the type of exception to catch, in my case, a timeout exception.

There are two properties to set here:

  • Exception Object Type
  • Exception Object Name

In my case this will be

Exception Object Type = System.TimeoutException (I had to choose .NET Class and navigate through the mscrolib again)

Exception Object Name = e ( I chose e, as this is what we use in coding most of the time, you can choose anything you like)

So the Exception Object Name is similar to doing this:

catch (Exception ex)



This is how looks is now.


Don’t forget to add custom code to handle the exception in the Catch Block, maybe to update a log table or send a message somewhere, like I have done above, so now when a web service times out, the orchestration will throw a timeout exception, this is much more intuitive than seeing a general exception!

SOAP exceptions from a web service

In order to catch soap exception from a web service, what you do is add a reference to the BizTalk project for:



Then add an exception handle block:



You can then access the information of the exception message like this:




Or you can create a Soap Exception message and send it to the message box for failure routing, here is an example from:, accessed 26 May, 2008

Source: Saravana Kumar,


A word of warning, if a web service throws a soap exception, the port will retry by default 3 times at intervals of 5 minutes, I changed the retry here to 0 for my example, so that the soap exception is caught and a log in made in SQL, however if you using a delay shape make sure the amount in the delay is greater than the total interval in the send point, else you will never catch the soap exception and will just catch timeout exceptions!

So below, works fine with a delays of 2.5 minutes, however if I made retry count = 1, then the delay should be greater than 5 minutes! You can really get confused when a soap exception occurs and the orchestration does not catch it, it will only catch it after the retry count is done in the send port of the web service!


Here is the exception in SQL

To recap:

  1. Create a VARIABLE in the orchestration view of the exception type you want to catch, use mscorlib to assign the variable type to an exception
  2. Drag a throw shape and set the type of exception to throw to the variable name (yes it is automatically instantiated)
  3. Add a custom Catch block to the SCOPE where the throw shape is located and once again, set the properties of Exception Object Name and Exception Object Type, where type will come from mscorlib and name is anything you like!

I would appreciate any comments you have or if you need any assistance with a BizTalk project. In later blogs I will be discussing Windows Communication Foundation and BizTalk R2.

Tip of the Day: Orchestrations should be used scarcely! The BizTalk books out their do not do any justice about this, since their main content is orchestrations and less on pure Content Based Routing using the core messaging engine i.e. Send Ports, Receive Ports, Adapters and Pipelines.

Secondly remember to always utilize serializable components if calling external components from within an orchestration, if you cannot encapsulate them by calling a web service, this ensures the calling code is dehydration friendly!


  • Uncategorized

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s