A developers guide to handling exceptions in BizTalk Server 2006/2009/2010
4.67/5 (13 votes)
This article explains how to handle exceptions in BizTalk Orchestrations
Introduction
Most of us might have written code to handle exceptions in any programming language. In BizTalk, exception handling is done a bit differently. This article explains how to handle exceptions and notification mechanism in ports using BizTalk.
Why Does One Need to Handle an Exception?
Consider the following cases:
- What happens when a BizTalk Send Port is unable to transmit a message to a remote server?
- Is there a way to retry a transaction in BizTalk orchestration or retry infinite number of times until the remote server is ready to consume messages.
- Is there a way to terminate an Orchestration gracefully when an exception occurs.
- How will you notify BizTalk administrator via email in case an exception occurs?
How are Exceptions Handled in BizTalk Orchestrations?
An exception is an exceptional condition that interrupts the regular flow of operation.
A scope shape in BizTalk is used to handle an Exception. There are two kinds of Exceptions in BizTalk orchestrations:
- Exception (regular .NET exception)
- General Exception
Exceptions in BizTalk orchestration are handled using a 'scope' shape. You must place all the logic for which an exception needs to be handled within a scope shape. The scope shape defines an exception section where an exception can be gracefully handled.
It is required to set the scope's transaction type property to 'none'. This shall avoid the overhead of a transaction, but still have the ability to handle exceptions.
What is the Difference between Exception and General Exception?
When we create a new exception handler, notice that in the property “Exception Object Type", the only item in the list is 'General Exception'. A General Exception in BizTalk is similar to writing a try-catch block but without the exception object, which means it's not possible to get the exception object. A general exception allows BizTalk to deal with any exception it may catch and re-throw, but there is no way to get the exception message at that point.
An 'Exception' is one that derives from the .NET exception object. Using this exception object type, it is possible to get the Exception object and its corresponding properties. Notice the property “Exception Object Name” for the Exception type. This will NOT be present in the case of a General exception.
Exception vs Delivery Notification
A Delivery Notification is a property which is set to indicate that the Send Port adapter will send delivery notification back to the orchestration to indicate the successful transmission of a message.
The 'Delivery Notification' flag on the Send Port indicates that the Orchestration must be notified back, in case the message has not been transmitted to the destination.
It's important to note that delivery notification works only when the 'Retry count' property on the send port is set to 0.
Delivery Failure Exception in Detail
When a message cannot be delivered on a Send Port with the DeliveryNotification property set to “Transmitted”, a DeliveryFailureException is raised and the exception needs to be handled by the orchestration. When you enable Delivery Notification, the orchestration will wait for an ACK/NACK to be returned when the message is transmitted. If an ACK is returned, the orchestration will complete the scope shape and continue processing. If a NACK is sent back from the engine, then the orchestration will raise a Microsoft.XLANGs.BaseTypes.DeliveryFailureException which is why the code needs to catch this type of exception.
Scenario 1: Sending a Sales Report
Consider a scenario where a sales report needs to be uploaded to a Web service.
Assumptions:
- If the Web service is not responding, it shall be online only after 24 hrs.
- The retry count and interval on the Web Service Port is set to "
0".
If the Web service is not responding, an exception is raised, and is handled by sending the message to an Offline folder.
 |
|
Event Log Messages...
Observe the event log messages...
Scenario 2: Raising the 'DeliveryFailureException' using a Dummy Folder
In this scenario, we create a "Dummy" folder when messages need to be transmitted, and since the Dummy folder does not exist, we handle an exception and send the messages to the Offline folder.
 |
|
Event Log Messages
Observe the event log messages:
About the Downloadable Code
- Unzip the Web Service with the folder names into the C:\inetput\wwwroot directory and setup the web service.
NOTE - Rename the Persist.asmx to Persist2.asmx so as to make it unavailable. - Unzip the BizTalk project zip file with the folder names in the C:\ drive.
- The folder KeyAndBindings contains the Bindings.xml file, which can be imported after the solution is built and deployed.
- Place the SalesMessage in the In folder and check the Offline folder.
Some Takeaways
- Set the
Synchronizedproperty on theScopeshape totrue, in the case you want to handleexceptions. - Always select the "
WebPortType" created when the "Web Reference" is added to the project, while creating "Web Ports" in the Orchestration. - Delivery Notification is not available on early bound ports. It is recommended not to use early bound ports. Use Early bound ports for learning and training purposes only.