Table of Contents

Instructions for debugging .NET nanoFramework native code in VS Code

About this document

This document describes how to debug .NET nanoFramework native code using VS Code.

Prerequisites

You'll need:

Preparation

You'll need a binary image with debug information to be loaded in the SoC or MCU. Assuming you are using VS Code to launch your builds, you'll have this image ready to be loaded in the MCU. (see Build instructions documentation)

In order to launch the debug session you'll need to setup the launch.json file, located in the .vscode folder. We've provided a template file launch.TEMPLATE.json (inside .vscode folder on the repository) to get you started with this. Just copy it and rename to launch.json.

Here's what you need to change in order to adapt the template file to your setup and make it more suitable to your working style and preferences.

  • name: here you can name each of the launch configurations to help choosing the appropriate one when launching the debug session. These could be for example: "nanoBooter in Discovery 4", "nanoCLR in Nucleo F091RC", "test featureXYZ in Discovery 4".
  • miDebuggerPath: full path to the gdb executable (this one is inside the GCC tool-chain folder)
  • program: full path to the .elf output file that results from a successful build
  • setupCommands (fourth 'text' entry): full path to the final image (the .hex file)
  • setupCommands (fifth 'text' entry): the same as the program entry above (the .elf file)
  • debugServerPath: full path to the OpenOCD executable
  • debugServerArgs: full path to the scripts directory on the OpenOCD installation AND the appropriate .cfg files for the interface and the board.

Note 1: VS Code parser seems to have trouble parsing and replacing the ${workspaceRoot} for some OpenOCD commands. That's the reason why you see there the ${workspaceRoot} variable and in other places the full path were that variable would make sense to be at. Just use what's there to keep OpenOCD happy. Note 2: Always mind the forward slash in the paths above, otherwise you'll get into troubles with strange and unclear errors from OpenOCD.

Templates

To make your life easier, we provide templates with pre-configured launch.json for the various reference targets. Just grab them from our Gist.

Launch the debug session

Using VS Code menu View > Debug, clicking on the debug icon on the left hand toolbar or hitting the CTRL+SHIT+D shortcut you'll reach the debug view. There you'll find the launch configurations for debug that we've setup above (see the drop down at the top) and the familiar green play button (or F5 if you prefer).

When a debug session is active you can find a lot of familiar stuff:

  • debug toolbar with the usual operations (pause, step over, into, out, restart and stop)
  • variables list
  • call stack that you can use to navigate up and down
  • breakpoint list to manage those
  • watch expressions
  • support for 'mouse over' a variable which will display a context with the variable content
  • ability to set/remove breakpoints by clicking near the line number
  • other handy tools and options using the right click on the various objects
Edit this page