BizTalk Training – Handling Exceptions inside orchestration

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 a New Exception Handler, in the 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.

Orchestration Scope General Exception

How can I get an Exception Message?

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

  • In the Exception Object Type property, select: <.NET Exception…>
  • In Artifact Type windows, select System.Exception
System Exception inside Scope shape

By selecting another type, you are able to define “Exception Object Name”, in this case, “ex”, and then for accessing 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, describing 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 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 the error message, just: “ex.Detail.InnerText”

Source Code


You can download the source code from GitHub here:

Hope you find this helpful! So, if you liked the content or found it useful and want to help me write more, you can help us buy a Star Wars Lego for my son! 

#1 all-in-one platform for Microsoft BizTalk Server management and monitoring
Author: Sandro Pereira

Sandro Pereira lives in Portugal and works as a consultant at DevScope. In the past years, he has been working on implementing Integration scenarios both on-premises and cloud for various clients, each with different scenarios from a technical point of view, size, and criticality, using Microsoft Azure, Microsoft BizTalk Server and different technologies like AS2, EDI, RosettaNet, SAP, TIBCO etc. He is a regular blogger, international speaker, and technical reviewer of several BizTalk books all focused on Integration. He is also the author of the book “BizTalk Mapping Patterns & Best Practices”. He has been awarded MVP since 2011 for his contributions to the integration community.

10 thoughts on “BizTalk Training – Handling Exceptions inside orchestration”

  1. Hi, It is really nice to see your post. But I am a fresh newbie without any programming background. I have orchestration designed, I want to catch any kind of exception. I consume wcf-sql adapter to get stored procedure in SQL DB. Then I used file adapters to file-in, file-out, and file-Exception Messages. I put shapes into the scope, and chose a new exception handler, and gave it a name and .net type, system.exception. And defined a variable, System.Xml.XmlDocument type.
    I have tried so many times, but no working… can pass the right xml, but the error will only show in the biztalk admin console’s event log… Would you please help me? Give me some hints?

  2. Hi Sandro,

    I’ve been benefit from your very resourceful and helpful blog for a while. Lately I ran into this post and associated links. I am unable to capture the Delivery Failure Exception. It seems “Delivery Failure Exception” will not be thrown in static request-response port, Did I miss something here?


    1. Hi Michael,

      You have to go to Transport Advance Options tab on you Static Solicit-Response port, check the check box “Enable routing for failed messages” and set “Retry Count” value to “0”.

      On your logical request-response port (inside orchestration) you need to Enable the flag Delivery Notification to ‘Transmitted’

      1. Hi Sandro,

        Thanks for your prompt response. Yes, I did set physical and logical port as you indicated. However, the last “General Exception” handler catches the exception rather than the “Delivery Failure Exception” handler right above “General Exception”. Neither did System.SystemException catch it as well. I re-read Naveen’s post you provided and it seems to me that “Delivery Failure Exception” capturing mechanism only works for one way transport. I am not sure though, as I don’t have luck. Could it because the adapter difference between BizTalk 2006 R2 and latest version? What else I might be missing?


      1. Yes, I did. The 1st exception handler that I set the exception object type to “Microsoft.XLANGs.BaseTypes.DeliveryFailureException ” did not caught the Delivery Failure Exception. After poke around, the SOAP Exception set to object type “System.Web.Services.Protocols.SoapException ” that I put right after the “Delivery Failure Notification” handler caught the exception instead.

        One of the MSDN BizTalk 2006 R2 product document that I have found seems indicating that as well, saying “This applies only to one-way operations; failure in two-way (request-response) operations results in a SoapException (negative acknowledgement) even without the port attribute being set.”. However, I am not sure if this has been changed in newer version of BizTalk Server after 2006 R2 though.

        If interested, the MSDN URL is:

        With several complex orchestrations chained to automate the processes, and each orchestration with a couple of Web Services calls, trying to catch the system/environment issue in transport layer(e.g. web service down, network issues) and react properly instead of wait for suspension, aside from SOAP Exception what’s the best practice of exception handling structure in chained orchestration you would recommend?


  3. Hi Michael,

    can you help me on getting the delivery exception in detail using SOAP Exception set to object type “System.Web.Services.Protocols.SoapException, which you mentioned above.

  4. Hi Sandro,
    Are you sure that is mandatory to set the “retry count” to 0 ? I’m asking because this is not mentioned in the BizTalk Server Documentation.

Leave a Reply

Your email address will not be published. Required fields are marked *


Back to Top