Introduction

On this page, we will cover the following:

1. Development environment recommendations
2. Extracting and opening the Extension contained in DebuggingDemo.zip
3. 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”:

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):

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:

properties:
  agent:
    log_level: 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:

properties:
  agent:
    log_level: Info
api:
  dynamic_choice_commands:
    exclude_file_ext:
      - name: 
        log_level: Inherited

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:

properties:
  agent:
    log_level: Info
api:
  dynamic_choice_commands:
    exclude_file_ext:
      - name: efe1
        log_level: Inherited

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:

< Previous     Next >