Skip to content

Usage Guide

Jump to bottom
Bogdan Mihaiciuc edited this page Dec 11, 2022 · 7 revisions

Debugging using ThingworxVSCodeDebugger

This guide will help you get started with debugging your Thingworx projects created with the ThingworxVSCodeProject using this extension.

You should only use this with a local Thingworx server dedicated to development. The debugger extension will expose a lot of information about your running services and will impact runtime performance.

Setting up

There are two extensions that are required to enable debugging - one for Visual Studio Code and one for Thingworx. You will also need to configure your Thingworx project for debugging.

Setting up Visual Studio Code

  • Download the latest ThingworxVSCodeDebugger extension from the releases page.
  • In Visual Studio Code, go to the Extensions tab, select the actions menu and choose Install from VSIX..., then select the extension you just downloaded.
    • You may be asked to reload Visual Studio Code to activate the extension. Install From VSIX
  • If you are using a self-signed certificate, you will need to get Visual Studio Code to trust the certificate by adding it to your OS certificate store.

Setting up Thingworx

  • By default, recent versions of Thingworx have default timeout of 30 seconds after which services will be forcefully stopped. Since debugging counts against this timeout, you should configure your script timeout to a sufficiently large value to prevent your debugging sessions from being terminated prematurely. To do this, open your platform-settings.json file and add or adjust the "ScriptTimeout" property under "BasicSettings". More information about platform-settings.json can be found in the official documentation.
  • Download the latest BMDebugServer extension from the releases page.
    • Thingworx will inform you that a server restart is required for the changes to take effect.
  • After Thingworx restarts, navigate to Subsystems in composer, and select the BMObservingDebugger subsystem.
    • By default, the subsystem will be disabled. To enable it, select the Enabled checkbox. Optionally, you may also select the Auto Start checkbox to cause it to start automatically when the Thingworx server is restarted.
    • 🖐 NOTE: While this subsystem is running, any newly created services will run in interpreted mode, which will have a negative impact on performance. Enable Subsystem

Configuring your project

  • Open your Thingworx project and create a launch configuration for Thingworx. To do this, go to the Run & Debug tab and click the gear icon - A file launch.json will open. Launch Configuration
    • Newly created projects will have a sample configuration by default; you should just change the appropriate fields
    • You may also add one yourself to any existing project. You may copy the configuration below and change the appropriate fields:
{
    "type": "thingworx-vscode",
    "request": "attach",
    "name": "Attach to Thingworx",
    "thingworxDomain": "localhost",
    "thingworxPort": 8015,
    "thingworxAppKey": "abc-def",
    "useSSL": false
}
  • In your package.json file, ensure that your "bm-thing-transformer" dependency is at least version 0.17. If you need to change the version, run npm install after saving the package.json file.
  • Create and upload a debug build to your Thingworx server that has the debug server extension install. To do this, run twc build --debug or twc upload --debug. Newly created projects will also have the buildDebug and uploadDebug tasks configured for them.
    • NOTE: You will need to redeploy your projects after any server restart. This is because the things may be initialised before the debug subsystem starts, which causes their services to not run in interpreted mode.
    • 🖐 NOTE: Even if the debug subsystem is disabled, debug builds will have a lot of extra instructions added to them, which will affect their performance.
    • NOTE: Debug builds cannot be used on servers that don't have the debug extension installed. If you do install a debug build on a server without the debug extension, all services will fail to execute.

Starting a debug session

  • Open your Thingworx project in Visual Studio Code.
  • Go to the Run & Debug tab and select your previously created attach configuration, then click the green "play" button.
  • Add breakpoints where you want execution to pause.
    • You may optionally enable the Exceptions breakpoint, available at the bottom of the debug sidebar. This will cause execution to automatically pause whenever any error is thrown. This should also pause for exceptions thrown from java services.
  • Launch the service you want to debug in any way:
    • From the composer
    • From a mashup
    • Directly using the debug console (e.g. typing something like Things.MyThing.myService())
  • For more information about debugging in Visual Studio Code, see the official documentation.

Debug Session

Clone this wiki locally