Debugging

Debugging the SDK code and tests with Visual Studio Code

Obviously you should feel free to use whatever code editor you like, the SDK is not prescriptive in that regard. Most members of the team use Visual Studio Code.

The configuration indicated below is as simple as possible on purpose, in order to limit the number of dependencies or tools that are needed to quickly get the environment setup. There are tools that can automate some of those manual steps (such as gulp/grunt, ts-node, etc) but our goal here is, once again, to minimize the number of dependencies to download and stars to align for the debugger to work as expected.

Visual Studio Code uses .map files to understand which line of Typescript code correspond to which line of generated Javascript code. .map files are automatically generated by the Typescript compiler (tsc) and placed in the same folder as Javascript files. These files are not checked-in, nor shipped with NPM packages, since they consist only of metadata useful for debugging.

There are 2 different debugging situations: debugging code (such as samples), and debugging tests. The latter is different from the former because tests require to be run using the mocha executable whereas simple code can just be passed as an argument to the Node.js executable directly, and Visual Studio Code knows how to handle that seamlessly.

Visual Studio Code uses a launch.json file to know what configuration to run. Here's a simple sample configuration entry to debug samples:

{
  "type": "node",
  "request": "launch",
  "name": "TS Simple Device Sample",
  "program": "${workspaceRoot}/device/ts-samples/sample_device.ts",
  "args": [
    "<device connection string>"
  ],
  "env": { }
}

Before running the sample, don't forget to run the typescript compiler to regenerate the updated Javascript and .map files. It is also possible to automate this by using the preLaunchTask option and a tasks.json file.

Debugging tests is a little different since the program we need to run is the mocha executable, and mocha takes Javascript scripts for arguments. Although the tests are written in Javascript, you want to be able to step into the Typescript source of the SDK. For this to work, 2 things are required:

• The sourceMaps property is mandatory if you want to see the debugger step into Typescript code instead of javascript
• Setting protocol to inspector is necessary if you want to be able to hit breakpoints in the Typescript code of the SDK

{
  "type": "node",
  "request": "launch",
  "name": "Http Unit Tests",
  "program": "${workspaceRoot}/device/transport/http/node_modules/mocha/bin/_mocha",
  "args": [
    "${workspaceRoot}/device/transport/http/test/_http_test.js"
  ],
  "protocol": "inspector",
  "sourceMaps": true,
  "env": {
    "IOTHUB_CONNECTION_STRING": "<IoT hub connection string>"
  }
}

The same configuration is valid to run tests written directly in Typescript. If that's your use-case, again, dont' forget to run tsc or to use pre-launch tasks in order to have the proper Javascript and .map files ready when the debugging session starts. Another option when using mocha is to use a pre-processor that takes care of compiling the code, such as ts-node.