Introduction

On this page, the debugging functionality will be documented in its entirely:

1. "UIP DEBUG CONFIGURATIONS" View
2. Plugin Dependencies
3. configurations.yml
4. Universal Extension API Levels
5. Launching/Debugging
6. Output Only Fields and Publishing Events
7. Output Channels
8. 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 changes

• template.json changes (during UIP: 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:

...

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.

...

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:

...