Exception handling with the BizTalk ESB Guidance

Yesterday I gave a presentation (together with Marcel Fernee of Microsoft) at the Dutch BTUG meeting (http://www.btug.nl) on my experience with the ESB Guidance. Part of the presentation was about the ESB Exception Management Framework and how I use it in the project I am working on.

Quote from the ESB Guidance documentation:

Using the ESB Failed Orchestration Exception Routing mechanism, the process steps are:

  1. Code in the exception handler that detects the error creates a fault message by calling the CreateFaultMessage method. For example:
    // Create fault exception message
    faultMsg = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.CreateFaultMessage();
  2. The Failed Orchestration Exception Routing mechanism automatically inserts the error description into the fault message context (for example, “The Business Rule Engine threw a divide by zero error processing the LoanProcessing policy”).
  3. The Failed Orchestration Exception Routing mechanism automatically promotes failure- and application-specific properties into the fault message context, setting the values from the current environment. These properties are:
    * Application (auto-populated)
    * DateTime (auto-populated as a UTC value)
    * Description (auto-populated—the exception message)
    * ErrorType (auto-populated—the exception type)
    * MachineName (auto-populated—the current server name)
    * Scope (auto-populated—the Scope shape containing the current exception handler)
    * ServiceName (auto-populated—the orchestration name)
    * ServiceInstanceID (auto-populated—the orchestration instance ID as a GUID)

    WARNINGS:
    The DateTime property is auto-populated with a string in the format of the servers regional date and time settings. If the format can not be mapped by the SQL server adapter, you will get a BizTalk error when the fault message is published to the Exception Management Database. My proposed solution can be found at http://www.codeplex.com/esb/WorkItem/View.aspx?WorkItemId=4430.

    If the auto-populated Description is larger than 256 characters BizTalk itself will give an error when the fault message is published to the message box, because promoted properties cannot be longer. This should be fixed in the source code of the ExceptionMgmt class.

  4. Code in the exception handler sets other properties of the fault message as required, for example:
    // Set fault message properties
    faultMsg.Body.FailureCategory = "MessageBuild";
    faultMsg.Body.FaultCode = 1000;
    faultMsg.Body.FaultDescription = "Some error occurred";
    faultMsg.Body.FaultSeverity = Microsoft.Practices.ESB.ExceptionHandling.FaultSeverity.Severe;
  5. The Failed Orchestration Exception Routing mechanism automatically serializes the current Exception object into the fault message.
  6. Code in the exception handler can optionally add current orchestration messages to the fault message using the AddMessage(faultMsg, messageToAdd) method. This serializes and persists the message, including all of the context properties. For example:
    // Add other current orchestration messages to the fault message
    Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.AddMessage(faultMsg, approvedRequestMsg);
  7. Code in the exception handler publishes the fault message through a direct bound port into the Message Box database.
  8. If publishing succeeds:
    * Orchestration or send port subscriptions can process the fault, rehydrating the Exception object, and extract any added messages complete with their context property values.
    * A global exception handler (a send port) automatically publishes the fault message to the ESB Management Portal.

Below is an example of the catch blocks that we us in our orchestrations. imageIn the Construct exception shape steps 1 to 6 are taken.

Then a Start Orchestration shape is called to start the ExceptionHandler orchestration in the figure below. This is also the place where step 7 is done. Here a very nice, but undocumented, feature of the ESB Guidance Core Framework can be used to log the exception: the EventLogger!

exception = Microsoft.Practices.ESB.ExceptionHandling.ExceptionMgmt.GetException(faultMsg);
Microsoft.Practices.ESB.Exception.Management.EventLogger.LogMessage(
    exception.Message,
    System.Diagnostics.EventLogEntryType.Error,
    (System.Int32)Microsoft.Practices.ESB.Exception.Management.EventLogger.EventId.Default
);

image

 

 

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: