Click here to Skip to main content
14,739,467 members
Articles » Enterprise Systems » Microsoft BizTalk Server » General
Posted 7 Jan 2011

Tagged as


7 bookmarked

How To Handle Exceptions in BizTalk Server 2009 using ESB Toolkit 2.0

Rate me:
Please Sign up or sign in to vote.
3.75/5 (6 votes)
8 Jan 2011CPOL
This article demonstrates how easy it is to handle exceptions in Microsoft BizTalk Server 2009 using ESB Toolkit 2.0


This article demonstrates how easy it is to handle exceptions in Microsoft BizTalk Server 2009 view them using ESB Toolkit 2.0 (ESB Portal).

Use Case: Purchase Order Processing


Consider a simple scenario where a Purchase Order (PO) needs to be processed and PO acknowledgement needs to be generated. An exception needs to be raised in the case where the PO amount (POAmt) is less than or equal to zero.

How Does BizTalk ESB Toolkit Help Us?

It provides a building block for handling exceptions and viewing failed message(s) through the use of the ESB Portal.

How Do I Code An Orchestration to Send Fault Messages to ESB Portal?

Add the following references to your orchestration:

  • Microsoft.Practices.ESB.ExceptionHandling
  • Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults

Step 1: Determine the Scenarios where Exception Needs to be Handled

In order to effectively handle exceptions, brainstorm all the scenarios where exceptions are required to be handled.

Place a "Scope" shape around the points where exceptions need to be handled.

Step 2: Handle the Exception and Send the Fault Message

Create a fault message of type "Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults.FaultMessage", in the example I have used a multipart message for brevity.

Set the Fault message properties in a thoughtful manner.

// Create Fault Exception Message
FaultMsg = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.CreateFaultMessage();
FaultMsg.ESBFault.FailureCategory = "POFaults";
FaultMsg.ESBFault.Scope = "local";
FaultMsg.ESBFault.FaultCode = "InvalidPO"; // a string value
FaultMsg.ESBFault.FaultDescription = 
	"This PO is invalid. See the error for more details.";
FaultMsg.ESBFault.FaultSeverity = 

// Add each message to the Fault Message
Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(FaultMsg, POMsg);
Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(FaultMsg, POAMsg);

Notice that each message, in this case PO and POA messages are added to the Fault message, this will help to view the incoming and outgoing messages using the ESB Portal.


Finally, a direct bound send port is used to write this fault message to the message box.

ESB Portal

The screen shots illustrate the various views of ESB Portal:



What Else Can Be Done Using the ESB Exception Handling Framework?

Step 1: Develop a custom exception handler orchestration with a filter on the activatable receive shape set as:

(Microsoft.Practices.ESB.ExceptionHandling.Schemas.Property.FaultCode == "InvalidPO")

This will enable all the Fault messages to be routed to the custom orchestration from the message box and an appropriate action can be taken.

Step 2: Retrieve all the messages in a fault message using the code below.

Declare a variable of type "Microsoft.Practices.ESB.ExceptionHandling.MessageCollection" and assign the variable to the code shown below:


What Can You Do with the Built-in Exception Handling Web Service in the ESB Toolkit?

Any .NET application which is not a part of BizTalk can be used to submit "Fault" messages to the Exception Handling Web Service.

Find this web service installed at "http://localhost/ESB.ExceptionHandlingServices/ExceptionHandling.asmx". Note that a WCF flavor of this web service is also provided by the default installation.

The final task would be to generate a Fault message by referencing the web service in your .NET application and submitting this Fault message using the web method "SubmitFault".

Downloadable Sample Code

BizTalk Server 2009, Visual Studio 2008 and ESB Toolkit 2.0 has been used for this sample.



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


About the Author

Naveen Karamchetti
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)

Comments and Discussions

QuestionHow to construct the error message without using ESB Tool kit. Pin
Member 1107234511-Sep-14 9:13
MemberMember 1107234511-Sep-14 9:13 
GeneralMy vote of 1 Pin
rakesh.ims3629-Mar-12 1:41
Memberrakesh.ims3629-Mar-12 1:41 
GeneralRe: My vote of 1 Pin
Eduardo Ponzoni8-Oct-14 14:15
MemberEduardo Ponzoni8-Oct-14 14:15 
GeneralNice thread Pin
Salam Y. ELIAS10-Jan-11 7:47
professionalSalam Y. ELIAS10-Jan-11 7:47 

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.