Raspberry Debugger

A Visual Studio Extension for debugging .NET Core applications remotely on a Raspberry Pi

IMPORTANT: .NET 5.0 starting with the SDK 5.0.102 works now!

You can use Visual Studio Code to develop and debug .NET Core applications either directly on your Raspberry or remotely from another computer but until today, there's been no easy way to use regular Visual Studio to develop and debug applications for Raspberry.

The new Raspberry Debugger Visual Studio extension allows you to code your application on a Windows workstation and then build and debug it on a Raspberry by just pressing F5 - Start Debugging.

Requirements

Windows 10
Visual Studio 2019 Community Edition (or better)
Raspberry Pi running 32-bit Raspberry Pi OS
Raspberry user allowed to sudo
Windows Open SSH Client (installed automatically when required)

Features

Supports Raspberry Pi 3+ devices
Raspberry Pi OS 32-bit (we haven't tested other operating systems)
Console and ASPNET .NET applications supported
Configures SSH 2048-bit RSA key pair automatically
F5/Run debugging
- .NET SDK and VSDBG installations handled automatically
- Program files transferred to the Raspberry
Raspberry debugging can be enabled/disabled for specific projects
Project specific Raspberry devices
C# and Visual Basic (other .NET languages should work too)
Debug activity logs

Installation

You can install the Raspberry Debugger from within Visual Studio:

Start Visual Studio
Select the Extensions/Manage Extensions menu
Search for Raspberry Debugger
Double-click it to install

You can install also this from our GitHub releases page:

Go to GitHub releases page
Click the most recent release
Scroll down to the Assets second and expand the list
Click RaspberryDebugger.vsix to download it
You should be prompted to open it with the VisualStudio.Launcher.vsix. Click OK to install it
Otherwise, save the file to your desktop and double-click to install it

Configure your Raspberry

After setting up your Raspberry based on the instructions you received with it, you'll need to perform a couple additional steps to make it ready for remote debugging:

Enable SSH so the Raspberry Debugger will be able to connect to your Raspberry over the network: Start the Terminal on your Raspberry and enter these commands:
```
sudo systemctl enable ssh
sudo systemctl start ssh
```
You'll probably want to change the pi user password from the default raspberry if you haven't already done so.
Ensure that your Raspberry is connected to the network via WiFi or a wired ethernet.
You'll need to need to know the IP address for your Raspberry. Go back to the Terminal and enter this command:
```
ip -h address
```
You'll see something like this:

You're looking for an inet address. In this example, my Raspberry is connected to WiFi and so the connection information will be located under the wlan0 network interface. I've highlighted the interface and the internet address here.

When your Raspberry is connected to a wired network, you'll see the IP address beneath the eth0 network interface which I've also highlighted but there is no IP address listed because my Raspberry is not connected to a wired network.

Make a note of your Raspberry's IP address; you'll need it to configure a connection in Visual Studio.
Advanced: Your Raspeberry's IP address may change from time-to-time, depending on how your network is configured. I've configured my home router to reserve an IP address for my Raspberry so it won't change. You can do this too if you control your network or you may need to configure a static IP address on the Raspberry itself.

Your Raspberry is now ready!

Configure Visual Studio

On your Windows workstation:

Download the RaspberryDebugger.vsix file from the latest release on this GitHub repository and double-click it to install it on Visual Studio. Alternatively, you can install this from the Visual Studio Marketplace from within Visual Studio via Extensions/Manage Extensions (search for Raspberry Debugger).
Start or restart Visual Studio.
Create a connection for your Raspberry: Choose the Tools/Options... menu and select the Raspberry Debugger/Connections panel.

Click Add to create a connection. The connection dialog will be prepopulated with the default pi username and the default raspberry password. You'll need to update these as required and also enter your Raspberry's IP address (or hostname).

When you click OK, we'll connect to the Raspberry to validate your credentials and if that's successful, we'll configure the Raspberry by installing any required packages and also create and configure the SSH key pair that will be used for subsequent connections.

Your new connection will look something like this:
Configure your .NET Core project for debugging. Raspberry Debugger supports Console and ASPNET applications targeting .NET Core 3.1 and .NET 5 Open one of your project source files and choose the new Project/Raspberry Debug menu:

The project Raspberry settings dialog will look like this:

Click the Target Raspberry combo box and choose the Raspberry connection you created earlier or [DEFAULT] to select the connection with its Default box checked and click OK to close the dialog. You can use this dialog to assign specific Raspberry devices to your projects.

That's all there is to it: just press F5 to build and debug your program remotely on the Raspberry. Add a Debugger.Break() call in your program to verify that it actually works:

NOTE: The Raspberry Debugger relies on the Windows Open SSH Client which is installed by default for recent Windows 10 updates. If this is not installed for some reason, you'll see the following dialog when you start debugging. This requires a reboot. Click Yes to install (this takes a few minutes so be patient) and then save any work and restart your workstation.

NOTE: The first time you debug a program on your Raspberry it will take a minute or two to start because we'll be installing the .NET SDK and debugger. Debugging will start much faster the second time.

Console Project Debug Properties

When debugging .NET Core Console projects, you can pass command line arguments and environment variables to the remote program. We don't currently honor any other properties on this page.

ASPNET Project Debug Properties

When debugging ASPNET projects, you can pass command line arguments and environment variables to the remote program and you also have the option to start a browser on your workstation and have it display a page from your application.

Your web application will be deployed on your Raspberry on all network interfaces, using the port specified by the App URL.

Debug Logs

The Raspberry Debugger writes detailed log information to the Visual Studio Debug Output Window. This is designed to give you some idea of what happened when something goes wrong.

Under the Covers

Here are some brief comments describing how the Raspberry Debugger works.

SSH Keys

The Raspberry Debugger automatically generates and configures a 2048-bit RSA key pair for SSH autentication. This is actually generated on the Raspberry and the public key is added to the connection user's ~/.ssh/authorized_key file on the Raspberry.

The public and private keys are also persisted to on your development workstation in the %USERPROFILE%\.raspbery folder. You'll find a connections.json file there with the connection information and the key file will be persisted to %USERPROFILE%\.raspbery\keys.

You'll need to create connections with a username and password so we'll be able to create and configure the SSH keys and we'll use key authentication thereafter. You may remove the connection password after creating a connection if you wish, but for most situations we recommend that you leave the password in place.

If you reimage your Raspberry flash drive and configure the same Raspberry password, the Raspberry Debugger will be smart enough to realize the SSH key authentication failed and it will retry connecting with the password and reauthorizing the existing public key. This makes reimaging a Raspbery nearly seamless.

Raspbery Directories

The Raspberry Debugger installs the .NET SDKs to /lib/dotnet and the vsdbg debugger to /lib/dotnet/vsdbgand /etc/.profile is updated to set DOTNET_ROOT=/lib/dotnet and DOTNET_ROOT is also added to the PATH.

The programs being debugged will uploaded to ~/vsdbg/NAME where NAME is the name of the program output assembly file.

Project Raspberry Debug Settings

The Project/Raspberry Debug Settings menu persists the settings to the new $(SolutionDir)\.vs\raspberry-project.json file. This keeps track of which Raspberry connection your projects will use or whether Raspberry debugging is disabled for projects. We put the file here because these are really developer specific settings and source control solutions are typically be configured to not track files in this folder.

Limitations

.NET Core is not supported on Raspberry 1, 2, or Zero cards
64-bit Raspberry Pi OS is not supported
.NET Core SDKs older than 3.1 are not supported
Start Without Debugging or Attach to Process... are not supported (yet)
Raspberry debugging uses the default project debugging profile
HTTPS is not currently supported for ASPNET debugging
Program assembly names can't include spaces

Disclosures

The Raspberry Debugger extension is compatible with Raspberry Pi
Raspberry Pi is a trademark of the Raspberry Pi Foundation

schorges / RaspberryDebugger