The biggest and we hope the most important and useful serviceability improvement in RPE 1.3 is the Debugger. The debugger allows monitoring the document generation and inspecting the data and variables at any point.
The debugger is available in Document Studio, works for local document generation only and cannot be attached to a running instance of RPE.
There are 5 areas in the Document Studio UI exposing the debugger functionality ( see the above image):
- The main toolbar has the debugger controls
- A status bar shows the status of the debugger (running or stopped on a breakpoint)
- The execution context gives an overview of the variables and data values at the breakpoint
- The details view shows the raw value as well as the XHTML source ( if that’s the case) of the selected variable or data source property
- A replica of the debug controls in the main toolbar made available in the Debug View
Steps for debugging a template
- The user defines one or more breakpoints.
- The user starts the debugger (F11).
NOTE: at this point it is recommended to select the “Run in background” option from the document generation progress dialog.
- The debugger shows the progress by selecting the element currently processed by RPE.
- When an element with a breakpoint is reached the debugger will stop and the debug view will show the data and element context
- The user resumes the debugger using one of the 3 available options:
- Step Next – to move to the next template element
- Resume Debug – to move to the next breakpoint
- Resume Normal Execution – to exit debug mode and allow RPE to complete the document generation at normal speed
A breakpoint can be set/removed through the main/debug view toolbars or by using the context menu of the element.
NOTE: breakpoints cannot be defined in master pages
The debugger supports the following:
- Debug (F11) – starts RPE in debug mode enabling all the other capabilities
- Resume Next (F6) – advances the debugger to the next element in the template. The debugger must be stopped on a breakpoint for this command to be active
- Resume Debug (F8) – resumes the debugger. The debugger will stop on the next breakpoint or when the document generation is finished.
- Resume normal execution (Ctrl+F8) – resumes the execution and ignores all breakpoints
- Toggle Breakpoint – toggles on/off a breakpoint on the currently selected elements. Breakpoints can be set on any number of elements. The debugger will pause the execution when the element is reached
- Toggle Conditional Breakpoint – same as regular breakpoints but the debugger will only stop when the condition is met. Note that this condition is separate from any condition that might be defined on the template element and does not impact the output of the template
- Clear all breakpoints – removes all the defined breakpoints
NOTE: when defining a conditional breakpoint one can use only the data properties already used in the template. The condition editor allows using all properties but due the debugger’s implementation element properties not specified in the template will not be resolved.
Inspecting the context
When the debugger stops on a breakpoint the user can inspect the element and the data context at that point. The data context is made of the template variables and the data elements visible at that location.
The information currently shown is the element ID, element type, current recursion level and information if the condition on the element passed or not (if a condition exists).
The user can select the variables and data properties to see their value, including the XHTML source where that’s available. The detailed view is especially interesting for data sources that have rich text ( XHTML).