Orchestration Debugger

Working with the Orchestration Debugger

The following screenshot shows a typical debugging session in the Orchestration Debugger.

The Orchestration Debugger consists of three panes that are always present and two optional panes that appear when attached to an orchestration instance:

• The Service pane displays the instance service name and GUID that uniquely identifies the orchestration instance, debug mode, orchestration state, whether the Orchestration Debugger is attached, and service options.
  
  
• The Tracked Events pane lists the status of every action performed in the orchestration, such as whether it started or completed. As you select each of the rows in this pane, the corresponding shape in the Orchestration pane appears highlighted in green when the shape starts and blue when the shape finishes.
  
  
• The Orchestration pane is where a visual representation of the orchestration is rendered with all of its shapes.
  
  
• The Variable List pane appears when attached to an orchestration instance and displays the name, value, and type of the variable. The value indicates if the variable is null or, if not, then what kind of object it contains. Type is the Assembly.Namespace.Name of the object.
  
  
• The Variable Properties pane appears when attached to an orchestration instance and displays properties for the variable that vary according to the type of object. For example, for messages this includes Message Parts (including Name, Properties, Size, Type, and Value) and Message Properties (including Context, Name, PartCount, Scope, Type, and Value).
  
  

You will likely focus on the Orchestration, Variable List, and Variable Properties panes when debugging orchestration instances. Using the Orchestration pane, you can determine how a message is flowing through an orchestration, while the Variable List and Variable Properties panes show current variables and their properties, values, and types. This is useful for debugging decision shape errors, determining what content is reaching a port, seeing the "before" and "after" messages in a transform operation, and other tasks.

Resuming an Orchestration Instance

---

To resume the execution of an orchestration in the Orchestration Debugger, click Debug on the menu and choose Continue. The instance will continue execution until either another breakpoint (either class-level or instance-level) is hit or the orchestration completes.

Note
Tracked events will not be refreshed until you click Refresh on the File menu.

Debugging a Called Orchestration

---

If the orchestration calls another orchestration, you can debug the called orchestration by right-clicking the call orchestration action in the Tracked Events pane and then clicking View Called Orchestration. In the orchestration below, the Call Orchestration shape is named CallOrchestration_1.

Right-clicking the corresponding Call event in the Tracked Event pane and then clicking View Called Orchestration causees the Orchestration Debugger to load the called orchestration. In the above orchestration, notice that the title bar displays the instance's GUID as well as #0. This number represents the orchestration being called; the original orchestration is always #0. When the called orchestration is brought up, it will be #1 and so on.

You can return to the calling orchestration by clicking Debug and choosing View Calling Orchestration in the Orchestration Debugger. This works recursively so if your original orchestration (#0) calls another orchestration (#1) that in turn calls another orchestration (#2), you would need to choose Debug | View Calling Orchestration twice.

Debugging an Orchestration Instance That is Suspended (Resumable)

---

Orchestration instances that are in the Suspended (Resumable) state can be debugged by the Orchestration Debugger by resuming the instance in debug mode.

To debug a Suspended (Resumable) orchestration instance

1. Click Start, point to Programs, point to Microsoft BizTalk Server 2006, and then click Health and Activity Tracking.

2. On the HAT tool menu, click Queries, and then choose Most recent 100 service instances or one of the other query choices as appropriate to your situation.

3. In the search results, right-click an orchestration service instance that is in the Suspended (Resumable) state and then click Orchestration Debugger.

4. From the Orchestration Debugger, click Debug and choose Resume in Debug Mode.

   The Orchestration Debugger opens the orchestration instance in debug mode as if a breakpoint had been reached.

5. Debug the orchestration.

Debugging Orchestrations on a Remote Computer

---

You can use the Health and Activity Tracking tool to debug a remote computer provided the following conditions are met:

• The BizTalk Server Administration tools have been installed.
  
  
• You are a member of the BizTalk Server Administrators group on the computer where the BizTalkMsgDb exists.
  
  
• The SQL Server instance has been configured to allow inbound network connections.
  
  

Warning
Grant access only to individuals that require access. For more information about HAT and security, see Security Considerations for Health and Activity Tracking.

To connect HAT to a remote computer

1. Click Start, point to Programs, point to Microsoft BizTalk Server 2006, and then click Health and Activity Tracking.

2. On the HAT tool menu, click Tools and choose Preferences. This will bring up the Preferences screen.

3. Click Live Data, and then specify the Management SQL Server name and database name. In the example below, the HAT tool is configured to connect to the remote Management SQL Server BTS_MGMNT_SVR01 using the default management database named BizTalkMgmtDb.

   

4. Click OK.

Limitations of the Debugger

---

The Orchestration Debugger does not support the following scenarios:

• Debugging inside of a Message Construction shape. You can set a breakpoint on the Message Construction shape.
  
  
• Debugging inside of an atomic scope. You cannot set a breakpoint on shapes inside of an atomic scope or an orchestration that is defined as Atomic.
  
  
• Setting a breakpoint on a Group shape. You can set a breakpoint on individual orchestration shapes inside of the Group shape.
  
  
• Setting a breakpoint on a compensation block. You can set breakpoints on the actions inside of the compensation block.
  
  
• Setting a breakpoint on a catch block. You can set breakpoints on the actions inside of the catch block.
  
  

You should also be aware of the following considerations when using the Orchestration Debugger:

• If you track an orchestration modified without changing the version number, you must restart all the host instances to which the orchestration is enlisted. This ensures that any shape change in the newly deployed version displays correctly as you step through the Orchestration Debugger
  
  
• When you attach to an instance in the Orchestration Debugger, any atomic scopes in the orchestration instance will cause gaps to appear in the tracked events list. This happens because events for the shapes inside atomic transactions do not get persisted until the scope commits and because the debugger reloads events onto the end of the list, so any gaps remain unfilled during the live session.
  
  

  Note
  You can eliminate gaps in the tracked events list by refreshing the view.

If you need to capture detailed information about program flow, variable contents, versions and other diagnostics you may want to use Debug and Trace statements as explained below.