1. Problem
You need to define how your orchestration behaves under possible exception conditions.
2. Solution
Any orchestration can have
Scope shapes in it. Place other orchestration shapes within the Scope
shape to define the expected behavior of the orchestration. If BizTalk
encounters an exception performing the steps inside a Scope shape, it
will jump to separate actions defined in an exception handler. The
solution demonstrates how to add exception handling to an orchestration.
NOTE
A scope functions exactly like a traditional try/catch block.
Create a new orchestration. Drag a Scope shape from the toolbox onto the orchestration design surface.
Right-click the name of the Scope shape, and select Properties from the context menu.
Set the Transaction Type property to None and the Name property to Controlled Exceptions Scope.
Right-click the name of the new Scope shape, and select New Exception Handler from the context menu, as shown in Figure 1.
Right-click the name of the exception handler created in the previous step, and select Properties Window from the context menu.
Set the Exception Object Type property to General Exception and the Name property to Log Exception, as shown in Figure 2.
From the toolbox, drag an Expression shape into the exception handler.
Double-click the Expression shape to open the Expression Editor, and add the following code to record the exception.
System.Diagnostics.EventLog.WriteEntry("A Simple BizTalk Source",
"An exception was encountered in my sample orchestration. ");
Build
the orchestration logic inside the Scope shape. If BizTalk encounters
an exception processing the orchestration logic, it will invoke the
Expression shape.
3. How It Works
The BizTalk Orchestration
Designer is a development tool. Just as when building a component with
any other development tool, exception conditions can occur long after
the component is constructed. The developer may misunderstand how the
component should behave, or changes to the other systems BizTalk
interacts with may cause exception conditions. Regardless of the cause,
the developer always needs to plan for the unexpected.
NOTE
In addition to
defining how an orchestration reacts to possible exception conditions,
orchestration scopes can also define atomic or long-running
transactions.
This recipe demonstrates how
to respond to exception conditions by invoking an Expression shape that
writes an error message to the Windows application log. However, an
exception handler can define more rigorous error-resolution procedures.
The compensation block can simply log the exception, can invoke an
exception-handling framework, or can invoke another BizTalk
orchestration defining a series of resolution actions. In addition, if
an orchestration defines the procedures for resolving exceptions, then
the BizTalk Business Activity Monitor (BAM) can generate reports on
exception-resolution processes.
3.1. Error Information
This solution's example uses the default General Exception object type, as shown earlier in Figure 2.
This is useful when you want to log where and when errors occur but do
not need specific information about the actual errors encountered.
An exception handler can identify more specific error information when the exception handler's Object Type property is set to any class inheriting from System.Exception. When the Object Type is a .NET Exception, as shown in Figure 3, the exception object can retrieve additional information such as an error message.
Modify the Expression shape as follows to include the error message in the application log entry.
System.Diagnostics.EventLog.WriteEntry("A Simple BizTalk Source",
"An exception was encountered: " + ex.Message);
3.2. Multiple Exception Handlers
A single Scope shape can also
specify multiple exception handlers to define different reactions to
different exceptions encountered by the orchestration. When the Scope
shape encounters an exception, it will check each exception handler from
top to bottom. The Scope shape invokes the first exception handler
matching the type of exception encountered and stops looking for a
match. Therefore, more specific exception handlers must appear above
more general exception handlers, or the general exception handler will
handle all errors and the Scope shape will never invoke the specific
exception handlers. Define an additional exception handler with the
following steps.
Define the first exception handler as presented in this recipe's solution.
Right-click the name of the Scope shape, and select New Exception Handler.
Move
the handler for the General Exception defined in the solution by
selecting the name and dragging the mouse over the lower line defining
the new exception handler. The General Exception handler should appear
below the new one.
Right-click the name of the new exception handler, and select Properties Window.
Change the Name property to Handle Arithmetic Exception.
For the Exception Object Type property, select <.NET Exception...>. In the Select Artifact Type dialog box that appears, select the Arithmetic Exception, as shown in Figure 4, and then click OK.
Change the Exception Object Name property to ex.
Add shapes to the new exception handler to handle arithmetic exceptions specifically, as shown in Figure 5.
While a Scope shape will
invoke only the first exception handler matching the type of exception
encountered, sometimes there are consistent actions the orchestration
should take for different kinds of errors. For example, what if the
orchestration depicted in Figure 5-49
should call the orchestration for resolving math errors in addition to
logging the exception to the application log? The Throw shape can
propagate an exception from the Scope shape that initially catches it to
an outer Scope shape defining the consistent error actions. Figure 6 depicts an example of a Scope shape contained within another Scope shape.
NOTE
You can drag and drop the catch blocks from one exception block to another.
