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:

Open

Initially, configurations.yml will not be present, so the view will report that and show a button to “Add Configurations”:

Open

If there are any issues with configurations.yml, the view will report that and show a button to “See Problems”:

Open

If there are no problems and there is at least 1 valid configuration, the view will render the contents of configurations.yml (layout will differ depending on the structure of your configurations.yml):

Open

Hovering on each configuration entry should expose the following two icons:

Open

Clicking on the “star” icon will mark the selected configuration entry as the default one (Clicking again will deselect it). This will be indicated with a green circle to the left of the configuration entry name:

Open

The default configuration entry will persist even if after VSCode has been closed. Clicking on the “debug” icon (next to the “star” icon) will launch that specific entry.

To update the list of entries in the "UIP DEBUG CONFIGURATIONS” view, click the “refresh” icon:

Open

Clicking the “refresh” icon, however, should not be necessary. The view will automatically be updated when

• 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).

• debugpy module is required for the Python debugger on VSCode’s end (client) to connect to the debugging server on the Extension side.

• Universal Extension Bundle is a proprietary zip file which contains the Universal Extension Base Class code for all the supported API levels mentioned in the requirements section. Specifically, the bundle zip consists of a folder called bundle which has:

  • universal_extension_1.0.0.zip

  • universal_extension_1.1.0.zip

  • universal_extension_1.2.0.zip

  • universal_extension_1.3.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:

• C:\Users\<USER>\AppData\Roaming\Code\User\globalStorage\stonebranch.uip (Windows)

• /home/<USER>/.vscode-server/data/User/globalStorage/stonebranch.uip (WSL using remote access)

• /home/<USER>/.config/Code/User/globalStorage/stonebranch.uip (Linux/Unix)

Once extracted, there should be a folder called bundle in stonebranch.uip folder with all the zip files for each of the API versions. Note, the bundle only needs to be installed once.

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.

• If the user selects Path to universal_extension_bundle_1.2.0.zip, a file picker dialog will show up and let the user select only a zip file.

• If the user selects URL, they can specify a download link to the bundle zip. Upon selecting URL, 3 additional inputs will be shown:

  • One for the URL that must start with either http or https.

  • One for the username, if applicable. Can be empty.

  • One for the password/token, if applicable. Can be empty. User input will be masked out.

The plugin will attempt to download the file from the URL. If the URL does not point to a zip file, it will issue an error.

• If the user selects Gitlab Package Registry, they will need to specify a full URL to the project/repository whose Package Registry contains the bundle zip. For instance, assuming that the user has a project/repository called DummyProject,

  1. Upload the universal_extension_bundle_1.2.0.zip as a generic package to DummyProject's package registry using the steps outline in GitLab Generic Packages Repository | GitLab. If successful, you should see something like this:
     

     
     
     Note that shrey_test is a group, DummyProject is a project/repository. In the image above,
     - #1 shows the package name. This does not have to be universal_extension_bundle, but it makes sense to name it that, and it makes the job of finding the actual zip easier for the plugin.
     - #2 shows the package version. Once again, it doesn’t have to be 1.2.0, but it makes sense to keep it that.
     - #3 shows the actual, uploaded bundle zip. This must be named universal_extension_bundle_1.2.0.zip

  2. Assuming Gitlab Package Registry was clicked from the dropdown menu, the next prompt should be to enter the project/repository URL. This is the URL that takes the user to the project/repository’s landing page:
     

  3. Then the next prompt should ask for the Personal Access Token.

  4. Depending on how the package was uploaded in step 1, two things can happen:

     1. The plugin can find the universal_extension_bundle_1.2.0.zip given that the package name is universal_extension_bundle (#1 in Figure 49) and package version is 1.2.0 (#2 in Figure 49)

     2. The plugin cannot find the bundle zip because the package name and version are something other than universal_extension_bundle and 1.2.0. If so, the plugin will show another dropdown with all the packages, and the user must select the one that contains universal_extension_bundle_1.2.0.zip

Assuming the zip file is available, the plugin will verify it using checksums before proceeding further. This is the default, but the user can turn off checksum verification in the settings:

Open

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: