Setting Up Initial Debugging Configuration
Introduction
On this page, we will cover the following:
- Development environment recommendations
- Extracting and opening the Extension contained in
DebuggingDemo.zip
- Setting up initial debugging configuration for a
dynamic_choice_command
It is assumed the UIP Visual Studio Code Extension is already installed. See the previous document for installation instructions.
Step 1 - Development Environment Recommendations
In this and subsequent pages, Visual Studio Code will be running on Windows with the "Remote WSL extension" (WSL is Windows Subsytem for Linux). This set-up is essentially a Linux development environment running on Windows. This is not strictly required, as any platform that supports Visual Studio Code will work.
As mentioned in the previous page, the debugging functionality depends on the debugpy
PIP module. It is highly recommended to use a Python Virtual Environment to avoid dependency issues. See Using Python Environments in VS Code for using the Virtual Environment in Visual Studio Code.
Step 2 - Extract DebuggingDemo.zip
and Open the Contained Extension
Assuming DebuggingDemo.zip
has been downloaded from the previous page, go ahead and extract it to a known location (e.g. ~/dev
).
Open the extracted DebuggingDemo
folder in VSCode. The directory structure must be as follows for the plugin to work:
Now would be a good time to set up the virtual environment in VSCode.
Step 3 - Setting Up Initial Debugging Configuration for a dynamic_choice_command
To get started, click the “Stonebranch” icon on the activity bar, followed by a click on “DEBUG CONFIGURATIONS”:
Alternatively, you can also press F5
which will open the “UIP DEBUG CONFIGURATIONS” view
Now, click “Add Configurations” which should create and open a file called configurations.yml
(located in .uip/debug
) and suggest two items as shown below (if not suggested, press Ctrl+Space
):
configurations.yml
is used to configure to define debugging configurations. See Full Reference for details.
From the suggestion box, select properties
, then press Ctrl+Space
and select agent
, followed by another Ctrl+Space
and select log_level
. If you press Ctrl+Space
one more time, it will show all the log levels that can be possibly set. For now, select Info
:
As the structure implies, the log_level
object inside properties -> agent
is used to configure the Agent log level.
You may have noticed that the “UIP DEBUG CONFIGURATIONS” view no longer has “Add Configurations”. Instead, it is complaining that the configurations.yml file has errors, and they must be resolved. Click "See Problems", and it should show the following error:
The properties
object we added above is actually optional; the one that’s required is api
. The api
object is where the developer can target a specific feature of Universal Extensions. As of now, the api
object consists of extension_start
and dynamic_choice_commands
.
At the very beginning of the next line after log_level
, do the following Ctrl+Space -> api -> Ctrl+Space -> dynamic_choice_commands -> Ctrl+Space -> exclude_file_ext
:
You may have noticed that exclude_file_ext
object is an array of objects as denoted by the indented -
. This means that the Extension developer can write multiple “cases”/configurations for a given dynamic choice command.
For now, in the name
field, type in something unique to identify this (only) configuration. Upon save, the “UIP DEBUG CONFIGURATIONS” view should refresh automatically and show:
Press F5
, and you should get the following error notification:
In the “UIP DEBUG CONFIGURATIONS” view, hover over the efe1
entry and click the “star” icon as shown below:
Clicking the “star” icon sets efe1
as the default launch target. Once we add more configurations, setting a default will come in handy.