Debug .NET apps on Raspberry Pi

Debugging .NET apps running on ARM-based IoT devices like Raspberry Pi presents a unique challenge. If desired, you can install Visual Studio Code and the .NET SDK on the device and develop locally. However, the Visual Studio Code extension for C# is not compatible with 32-bit operating systems, so debugging locally from Visual Studio Code is not supported in these environments. In addition, even in a 64-bit environment, the device's performance is such that debugging locally is not recommended. Accordingly, this article describes how to debug .NET apps on Raspberry Pi and similar devices remotely from a development computer.

Tip

For the reasons described above, it's strongly recommended that you develop your app on a development computer and then deploy the app to the device for remote debugging. If you wish to develop and debug locally on the device, the following is required:

• A 64-bit OS, such as Raspberry Pi OS (64-bit).
• Visual Studio Code with the C# extension.
  • Disable the hardware acceleration.
• .NET SDK 6.0 or later.
  • Install using the dotnet-install script as in a framework-dependent deployment. Be sure to add a DOTNET_ROOT environment variable and add the .dotnet directory to $PATH.

Debug from Visual Studio Code (cross-platform)

Debugging .NET on Raspberry Pi from Visual Studio Code requires configuration steps on the Raspberry Pi and in the project's launch.json file.

Enable SSH on the Raspberry Pi

SSH is required for remote debugging. To enable SSH, refer to Enable SSH in the Raspberry Pi documentation.

Install the Visual Studio Remote Debugger on the Raspberry Pi

Within a Bash console on the Raspberry Pi (either locally or via SSH), execute the following command. This command downloads and installs the Visual Studio Remote Debugger on the Raspberry Pi:

curl -sSL https://aka.ms/getvsdbgsh | /bin/sh /dev/stdin -v latest -l ~/vsdbg

Set up launch.json in Visual Studio Code

On the development computer, add a launch configuration to the project's launch.json. If the project doesn't have a launch.json file, add one by switching to the Run tab, selecting create a launch.json file, and selecting .NET or .NET Core in the dialog.

The new configuration in launch.json should look similar to one of the following:

Self-contained

"configurations": [
    {
        "name": ".NET Remote Launch - Self-contained",
        "type": "coreclr",
        "request": "launch",
        "program": "~/sample/sample",
        "args": [],
        "cwd": "~/sample",
        "stopAtEntry": false,
        "console": "internalConsole",
        "pipeTransport": {
            "pipeCwd": "${workspaceRoot}",
            "pipeProgram": "C:\\Program Files\\PuTTY\\PLINK.EXE",
            "pipeArgs": [
                "-pw", "raspberry",
                "pi@raspberrypi"
            ],
            "debuggerPath": "~/vsdbg/vsdbg"
            }
        },

Notice the following:

• program is the executable file created by dotnet publish.
• cwd is the working directory to use when launching the app on the Pi.
• pipeProgram is the path to an SSH client on the local machine.
• pipeArgs are the parameters to be passed to the SSH client. Be sure to specify the password parameter, as well as the pi user in the format <user>@<hostname>.

Framework-dependent

"configurations": [
    {
        "name": ".NET Remote Launch - Framework-dependent",
        "type": "coreclr",
        "request": "launch",
        "program": "~/dotnet/dotnet",
        "args": ["~/sample/sample.dll"],
        "cwd": "~/sample",
        "stopAtEntry": false,
        "console": "internalConsole",
        "pipeTransport": {
            "pipeCwd": "${workspaceRoot}",
            "pipeProgram": "C:\\Program Files\\PuTTY\\PLINK.EXE",
            "pipeArgs": [
                "-pw", "raspberry",
                "pi@raspberrypi"
            ],
            "debuggerPath": "~/vsdbg/vsdbg"
            }
        },

Notice the following:

• program is the path to the .NET runtime on the Pi.
• args is the path to the assembly to debug on the Pi.
• cwd is the working directory to use when launching the app on the Pi.
• pipeProgram is the path to an SSH client on the local machine.
• pipeArgs are the parameters to be passed to the SSH client. Be sure to specify the password parameter, as well as the pi user in the format <user>@<hostname>.

Important

The previous examples use plink, a component of the PuTTY SSH client. OpenSSH, which is included in recent versions of Windows and Linux, may be used instead. However, OpenSSH doesn't support sending passwords as a command-line parameter. To use OpenSSH, configure your Raspberry Pi for passwordless SSH access.

Deploy the app

Deploy the app as described in Deploy .NET apps to Raspberry Pi. Ensure the deployment path is the same path specified in the cwd parameter in the launch.json configuration.

Launch the debugger

On the Run tab, select the configuration you added to launch.json and select Start Debugging. The app launches on the Raspberry Pi. The debugger may be used to set breakpoints, inspect locals, and more.

References

Remote Debugging on Linux ARM (OmniSharp documentation)

Debug from Visual Studio on Windows

Visual Studio can debug .NET apps on remote devices via SSH. No specialized configuration is required on the device. For details on using Visual Studio to debug .NET remotely, see Remote debug .NET on Linux using SSH.