BizTalk 2010 Recipes : Administration and Operations - Debugging Orchestrations

1. Problem

You need to debug a BizTalk orchestration.

2. Solution

You can use BizTalk's Orchestration Debugger, which allows you to set breakpoints on any shape in an orchestration. Once an instance of an orchestration executes and encounters one of these breakpoints, it will go into a wait state in the BizTalk MessageBox, allowing a developer or administrator to manually step through the orchestration.

The following steps demonstrate setting how to debug an orchestration.

3. How It Works

While the Orchestration Debugger can be a helpful tool, especially in cases where an orchestration is deployed in a production environment and is encountering errors, developers often need a much more rapid and controllable method for debugging. It is helpful to have logging in development and in production, and the ability to turn it on and off for any given process at any given time should be available. Several techniques enable this type of debugging.

For example, using two standard .NET lines of code will allow a view into what is happening in an orchestration without opening the Orchestration Debugger:

System.Diagnostics.EventLog.WriteEntry("Demo","Value: " + strValue);
System.Diagnostics.Trace.WriteLine("Value: " + strValue, "Demo");

The System.Diagnostic.EventLog.WriteEntry method will log entries to the Windows Event Viewer. To view this logged event, open the Control Panel, select Administrative Tools, and double-click Event Viewer. Events will be logged to the application log, and you'll need to refresh the display to see results as they are written.

The System.Diagnostics.Trace.WriteLine method will allow all of the trace outputs to be read by attaching to the main BizTalk executable and monitoring in Visual Studio. Use the following steps to do that monitoring:

One way to use the System.Diagnostic methods for debugging/tracing in orchestrations is to wrap the logging code in an If statement and create a TraceFlag that can be set in a configuration file, such as the BTSNTSvc.exe.config file in the root BizTalk Program Files folder. Here is an entry you could add to the BTNTSvc.exe.config file:

<add key=" TraceFlag" value="true"/>

Listing 1 demonstrates how to retrieve the TraceFlag and, based on its value, log information.

Example 1. Configurable Trace Flag

// set the trace flag based on a value stored in the BizTalk Config File
// note that blnTraceFlag must be defined in the orchestration variables


blnTraceFlag = System.Convert.ToBoolean(System.Configuration.
ConfigurationSettings.AppSettings.Get("TraceFlag"));

// set the source to something unique for this orchestration
strSource = "DebugDemoOrchestration";

// Trace
if(blnTraceFlag == true){
strValue = System.Convert.ToString(intValue);
System.Diagnostics.EventLog.WriteEntry(strSource,"Value: " + strValue);
System.Diagnostics.Trace.WriteLine("Value: " + strValue, strSource);
}

When using this approach, keep tracing information separate in the orchestration from other functionality, and label it appropriately. You can do this by dedicating an Expression shape to a single trace event and naming it Trace (for example), as shown in Figure 3.

Figure 3. Expression shape for tracing

One of the most helpful ways to debug is to see the actual XML of a message, especially before and after mapping. This can be done by setting a variable of type System.Xml.XmlDocument equal to an orchestration message and then tracing the value of this variable, as shown in Listing 2.

Example 2. Tracing XML

// set the xmlDoc variable equal to the message to be traced.
// msgOrch is an orchestration message
xmlDoc = new System.Xml.XmlDocument();
xmlDoc = msgOrch;
System.Diagnostics.EventLog.WriteEntry(strSource,"Value: " + xmlDoc.OuterXml);
System.Diagnostics.Trace.WriteLine("Value: " + xmlDoc.OuterXml, strSource);

					  

NOTE