Click here to Skip to main content
15,867,594 members
Articles / Programming Languages / C#

A developers guide to handling exceptions in BizTalk Server 2006/2009/2010

Rate me:
Please Sign up or sign in to vote.
4.67/5 (15 votes)
10 Sep 2011CPOL6 min read 189.6K   2.7K   55   18
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

ExceptionScope.JPG

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?

GeneralException.JPG

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.

SalesOrchestration




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.
WebPort
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...

EvtLogSales

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.

NotificationOrchestration




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".
DummyPort
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:

EvtLogNotification

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

  1. Set the Synchronized property on the Scope shape to true, in the case you want to handle exceptions.
  2. Always select the "WebPortType" created when the "Web Reference" is added to the project, while creating "Web Ports" in the Orchestration.
  3. 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

  1. Acknowledgments and Negative Acknowledgments (Part 1)
  2. BizTalk 2004 Delivery Notification and NACK Sample

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Architect AT&T Wi-Fi Services
United States United States
Naveen has done his Masters (M.S.) in Computer science, has started his career programming the mainframes and now has more than a decade of programming, development and design experience. Naveen has a sharp eye and keen observation skills. Naveen has worked for several companies and strived hard to build large scale business applications and bringing better solutions to the table.
Quite recently Naveen has built a fairly complex integration platform for a large bank. His hobbies include training, mentoring and research. Naveen spends his free time visiting National Parks nationwide.

Naveen has developed the BizTalk Control Center (BCC)
http://biztalkcontrolcenter.codeplex.com

Comments and Discussions

 
QuestionNeed Info : NACK and ACK Pin
Shrilata Ellaboina23-Nov-12 0:44
Shrilata Ellaboina23-Nov-12 0:44 
Questionquestion: failed in solution conversation Pin
use4forums27-Feb-12 10:44
use4forums27-Feb-12 10:44 
QuestionWhat is the url and the adapter to use Pin
Salam Y. ELIAS23-Jun-11 6:58
professionalSalam Y. ELIAS23-Jun-11 6:58 
Very nice article, can you please indicate
the URL of the WS to entered in the Port configuration SendPort2, is it "http://localhost/persiststoremessage/" or http://localhost/persiststoremessage/persist.asmx

2nd, which protocol should be used SOAP or HTTP

Thanks in advance
AnswerRe: What is the url and the adapter to use Pin
Salam Y. ELIAS23-Jun-11 7:57
professionalSalam Y. ELIAS23-Jun-11 7:57 
GeneralMy vote of 5 Pin
turtlis10-Mar-11 22:04
turtlis10-Mar-11 22:04 
GeneralThanks for your articl . Tha't very excellent . Pin
xz_king27-Feb-08 18:50
xz_king27-Feb-08 18:50 
GeneralBeginner Pin
Aunalisiraj20-Jan-08 21:28
Aunalisiraj20-Jan-08 21:28 
Generalno change is Event Log. Pin
rajatpk15-Jan-07 9:17
rajatpk15-Jan-07 9:17 
GeneralRe: no change is Event Log. Pin
Member 143534119-May-19 0:49
Member 143534119-May-19 0:49 
Generalwhy specify later Pin
Tareq Muhammad2-May-06 6:10
Tareq Muhammad2-May-06 6:10 
AnswerRe: why specify later Pin
Naveen Karamchetti2-May-06 19:31
professionalNaveen Karamchetti2-May-06 19:31 
QuestionHow to Configure the Web port to start the Orchestration Pin
Karthikcse10-Apr-06 0:43
Karthikcse10-Apr-06 0:43 
AnswerRe: How to Configure the Web port to start the Orchestration Pin
Naveen Karamchetti10-Apr-06 3:23
professionalNaveen Karamchetti10-Apr-06 3:23 
GeneralRe: How to Configure the Web port to start the Orchestration Pin
Karthikcse10-Apr-06 3:30
Karthikcse10-Apr-06 3:30 
GeneralRe: How to Configure the Web port to start the Orchestration Pin
Naveen Karamchetti10-Apr-06 4:20
professionalNaveen Karamchetti10-Apr-06 4:20 
GeneralRe: How to Configure the Web port to start the Orchestration Pin
Karthikcse10-Apr-06 18:38
Karthikcse10-Apr-06 18:38 
JokeRe: How to Configure the Web port to start the Orchestration Pin
Naveen Karamchetti10-Apr-06 23:59
professionalNaveen Karamchetti10-Apr-06 23:59 
GeneralRe: How to Configure the Web port to start the Orchestration Pin
Naveen Karamchetti31-May-06 17:55
professionalNaveen Karamchetti31-May-06 17:55 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.