Debug .NET Core on Linux using SSH by attaching to a process

Starting in Visual Studio 2017, you can attach to .NET Core and .NET 5+ processes running on a local or remote Linux deployment over Secure Shell (SSH). This article describes how to set up debugging and how to debug. For debugging scenarios using Docker containers, see Attach to a process running on a Docker container and the container tools articles instead. To debug Linux on WSL 2 from Visual Studio (no attach to process), see Debug .NET Core Apps in WSL 2 with Visual Studio.

Note

For debugging Linux running on Azure Kubernetes Service (AKS), Bridge to Kubernetes is recommended instead of attach to process.

Prerequisites

• On the Linux server, you need to install SSH server, unzip and install with either curl or wget. For example, on Ubuntu you can do that by running:

  sudo apt-get install openssh-server unzip curl
  

  SFTP must be enabled as well as SSH. Most SSH distributions install and enable SFTP by default, but that is not always the case.

• On the Linux server, install the .NET runtime on Linux, and find the page matching your Linux distribution (such as Ubuntu). The .NET SDK is not required.

• For comprehensive ASP.NET Core instructions, see Host ASP.NET Core on Linux with Nginx and Host ASP.NET Core on Linux with Apache.

Prepare your application for debugging

To prepare your application for debugging:

• Consider using a Debug configuration when you build the application. It is much harder to debug retail-compiled code (a Release configuration) than debug-compiled code. If you need to use a Release configuration, first disable Just My Code. To disable this setting, choose Tools > Options > Debugging, and then deselect Enable Just My Code.

• Make sure your project is configured to produce portable PDBs (which is the default setting), and make sure the PDBs are in the same location as the DLL. To configure this in Visual Studio, right-click the project, then choose Properties > General > Debug symbols.

Build and deploy the application

You can use several methods to deploy the app prior to debugging. For example, you can:

• Copy sources to the target computer and build with dotnet build on the Linux machine.

• Build the app on Windows, and then transfer the build artifacts to the Linux machine. (The build artifacts consist of the application itself, the portable PDBs, any runtime libraries it might depend on, and the .deps.json file.)

When the app is deployed, start the application.

Attach the debugger

When the application is running on the Linux machine, you are ready to attach the debugger.

1. In Visual Studio, choose Debug > Attach to Process….

2. In the Connection Type list, select SSH.

3. Change the Connection Target to the IP address or host name of the target computer.

   If you haven't already provided credentials, you will be prompted to enter a password and/or private key file.

   There are no port requirements to configure, except the port that the SSH server is running on.

4. Find the process that you would like to debug.

   Your code runs either in a unique process name or a process named dotnet. To find the process that you're interested in, check the Title column, which shows the command line arguments for the process.

   In the following example, you see a list of processes from a remote Linux machine over an SSH transport displayed in the Attach to Process dialog box.

   

5. Choose Attach.

6. In the dialog that appears, select the type of code you would like to debug. Choose Managed (.NET Core for Unix).

7. Use Visual Studio debugging features to debug the app.

   In the following example, you see the Visual Studio debugger stopped at a breakpoint in code running on a remote Linux machine.