...
Panel | ||||
---|---|---|---|---|
|
Introduction
On this page, the debugging functionality will be documented in its entirely:
- "UIP DEBUG CONFIGURATIONS" View
- Plugin Dependencies
- configurations.yml
- Universal Extension API Levels
- Launching/Debugging
- Output Only Fields and Publishing Events
- Output Channels
- Known Limitations
1 - "UIP DEBUG CONFIGURATIONS" View
The “UIP DEBUG CONFIGURATIONS” view located in the “Run and Debug” section is responsible for showing all the launchable configurations defined in configurations.yml:
...
configurations.yml
changestemplate.json
changes (duringUIP: Pull
)
2 - Plugin Dependencies
The debugging functionality has two dependencies: debugpy
PIP module, and Universal Extension Bundle (universal_extension_bundle_1.2.0.zip
).
...
The plugin has logic to install and setup both of the dependencies. For the bundle, however, additional steps are required on the user’s end.
2.1- Installing debugpy
If the plugin detects debugpy
is not installed in the active Python interpreter, it will go ahead and prompt the user to install it:
2.2 - Installing universal_extension_bundle_1.2.0.zip
The bundle zip is extracted and stored in:
...
If the plugin detects the bundle is not present in stonebranch.uip
, the plugin will show the following prompt:
If the user selects Yes
, then a dropdown will be shown to select the installation source.
...
Even if the verification is turned off, the plugin will still ensure the zip file consists of the bundle
folder, which itself should contain the files mentioned previously.
2.3 - Uses of universal_extension_bundle_1.2.0.zip
Aside from allowing the debugger to accurately launch/debug Universal Extension tasks, the bundle zip also adds autocompletion/suggestion functionality to extension.py
. For example, without the bundle installed, VSCode will complain that it cannot find the universal_extension
module:
...
With the bundle installed,
3 - configurations.yml
configurations.yml
(located in .uip/debug/configurations.yml
) is what the developer uses to define their debug configurations. At the top level, it consists of two objects:
...
Here is an example below showing how to use the fields:
4 - Universal Extension API Levels
As shown in the demo, the developer can change the API Level they want to target using:
Clicking on UE API: 1.3.0
in the screenshot above will allow the developer to easily change the API Level. No additional change is required.
5 - Launching/Debugging
Assuming configurations.yml
is correctly configured, and the plugin dependencies are installed, the developer can start debugging by simply pressing F5
.
...
The VSCode debug toolbar has also been enhanced to include a “Terminate” button:
This is used to force kill the Extension instance. This is useful if the Extension is stuck in an infinite loop (or in other blocking calls).
...
Clicking the “Cancel” button will call the extension_cancel
method. Since the Cancel functionality does not apply to dynamic choice commands, it will not be shown when a dynamic choice command is being debugged. Furthermore, the Cancel functionality was not available in API Level 1.0.0
, and thus, it will not be shown if the Universal Extension API Level in the Status Bar shows 1.0.0
.
6 - Output Only Fields and Publishing Events
Output only fields can be updated as usual using the update_output_fields
method from the ui
module (or using self.update_extension_status
method). For example,
...
Even though publishing events is supported, it isn’t all that useful since the concept of triggers and monitor does not apply to the plugin. They can be useful to verify the event is successfully configured/setup.
7 - Output Channels
There are four output channels that the Extension sends output to:
...
UIP (CONSOLE)
will contain miscellaneous output that is still useful, but doesn’t fit in STDOUT/STDERR/EXTENSION. As shown in the previous section, it contains the output of Output Only Fields and Events.
8 - Known Limitations
8.1 - Uncaught Exceptions
While debugging, if an uncaught exception occurs (e.g. a = 1/0
), VSCode sometimes opens the universal_extension.py
base class file with some additional pop-ups. This can be prevented by unchecking the Uncaught Exceptions
option in the Breakpoints section:
...