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.
 |
| Receive shape - Receives a Sales Report message. |
|
|
Scope shape - A scope defines a context in BizTalk. A scope is used to set a Transaction Type, in this case, the TransactionType is set to "None". The scope's Synchronized parameter is set to "true". |
|
|
| A Sales Report message is created, so as to transmit it to the web service. |
 |
| Note the properties of the Web Port which are marked in "Red". |
|
Delivery Notification - If a message fails to be delivered on a Port, the "DeliveryFailureException" is generated. Note that "Delivery Notification" is NOT available for Binding property "Specify Now". |
|
|
There are two kinds of Exceptions handled in this orchestration.
DeliveryFailure Exception - General Exception
|
|
| General Exception - In this case, the message which needed to be sent to the Web Service is written out to an Offline Folder. |
|
Important Note: DeliveryFailure Exception - This exception is not thrown in this scenario, since web service port is a request-response port. This is the reason why the exception is handled in the General Exception section. |
|
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.
 |
| Receive shape - Receives a Sales Report message. |
|
|
|
| A Sales Report message is created, so as to transmit it to the web service. |
|
Scope shape - A scope defines a context in BizTalk. A scope is used to set a Transaction Type, in this case, the TransactionType is set to "None". The scope's Synchronized parameter is set to "true". |
|
|
 |
Note the properties of the ReportDummyPort which are marked in "Red". |
|
Delivery Notification - If a message fails to be delivered on a Port, the "DeliveryFailureException" is generated. Note that "Delivery Notification" is NOT available for Binding property "Specify Now". |
|
|
There are two kinds of Exceptions handled in this orchestration.
DeliveryFailure Exception - General Exception
|
|
A DeliveryFailure Exception is raised by the Port, since the file path specified in the Dummy Port does not exist. The exception handler handles the exception by sending the message into the OfflineFolder. Notice that in this case, the DeliveryFailure Exception has been correctly raised. |
|
|
|
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
Synchronized property on the Scope shape to true, in the case you want to handle exceptions.
- 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.
References - Don't Miss These Great Posts
- Acknowledgments and Negative Acknowledgments (Part 1)
- BizTalk 2004 Delivery Notification and NACK Sample
