ESB Toolkit 2.0 comes with set of components that help you build loosely coupled ESB/SOA application on top of BizTalk Server 2009. You can take advantage of the ESB Toolkit by using only certain components of the package relevant to your application. One of the core components of the toolkit is the Exception Management Framework, which comes with the required helper components, web services, BizTalk ports, a sophisticated management portal etc that will help you build a standard and scalable exception management platform for your application without much custom coding.

It's always a problem for lot of us to get a starting point. In this post, I'll put a complete walk through of building a Hello World application to show you the basic idea of the Exception Management Framework in the ESB Toolkit. Before starting this exercise please make sure the ESB Toolkit is installed and configured correctly, and you got a working Exception Management Portal. Refer to my previous posts (here and here) showing how to set it up.

Solution:

Our sample application receives an Employee Request (id, firstName, lastName, Date of Birth) into an Orchestration. Age is calculated and an Employee Response (id, age) is send to an end point. If DOB field is invalid, it will result in an exception. The Orchestration got an exception handling logic (the way you do it normally using scope and exception handler). The only addition to "Catch Exception" logic is we construct the ESB fault message and submit it to MessageBox via Direct binding (no additional send ports required). The below figure shows the whole orchestration.

Step 1:

In order to use the ESB exception handling framework you need to reference couple of dlls. Add Reference to the following dlls inside your Orchestration project.

C:\Program Files\Microsoft BizTalk ESB Toolkit 2.0\Bin\Microsoft.Practices.ESB.ExceptionHandling.dll

C:\Program Files\Microsoft BizTalk ESB Toolkit 2.0\Bin\Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults.dll

Step 2:

Declare a new Orchestration message (ex: MSG_FAULT) and set the MessageType to Microsoft.Practices.ESB.ExceptionHandling.Schemas.Faults.FaultMessage, which you can find under the "Select from Referenced Assembly.." option.

Step 3:

Inside your Exception handling block construct the fault message (the one created in step 2) with relevant information required. The code will look like

   1: // Create Fault Exception Message

   2: MSG_FAULT = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.CreateFaultMessage(); 

   3:  

   4: //Assign some properties

   5: MSG_FAULT.FailureCategory = "Some User Category";

   6: MSG_FAULT.FaultDescription = ex.Message;

   7: MSG_FAULT.FaultCode = "3002002"

   8: MSG_FAULT.FaultSeverity =

   9: Microsoft.Practices.ESB.ExceptionHandling.FaultSeverity.Severe; 

  10:  

  11: //Add request message (any other message if present)

  12: Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(MSG_FAULT,MSG_EMP_REQUEST);

Step 4:

Create a "Direct" bound port and link this logical port with the send shape that's configured to send MSG_FAULT as shown in the above figure. Since its a Direct bound port no additional port configuration is required from your orchestration apart from your regular business related ones.

That's all really, how simple is it!!

Whenever there is an exception in our application an ESB Fault message will be generated and published to the MessageBox. Lot of properties will be promoted when this fault message is published, so you can construct your own error handling Orchestration to deal with the situation or have a send port configured to send email, send to MQ etc, etc the choice is yours. In addition to your own logic, the ESB Core application got a standard "All.Exception" send port (SQL Adapter) configured to capture any Fault message arising in the system and log it to the Exception management database. As part of the fault message lot of properties are added things like machine name, application name, service name, service instance id, etc etc which all gets inserted into the exception management database automatically and show up nicely in the portal as shown in the below figure taken from the management portal (default address http://localhost/ESB.Portal ).

Hope this gives a quick intro to get you started.

Nandri,

Saravana