Debugging ASP Core on Linux with Visual Studio 2017

Developer Support

Today’s post comes to us from Premier Developer consultant Randy Patterson.  It’s an excellent tutorial that walks you through setting up Visual Studio to remotely debug ASP.NET Core applications running on a Linux server.

.NET Core and specifically ASP Core is an Open Source, High Performance implementation of .NET that runs on Windows, Linux and Mac. After you deploy your web application to a Linux server it can be difficult to troubleshoot when issues arise. In this article, I’ll show you how to configure your Linux test server and Development environment to allow remote debugging giving you all the greatness of debugging in Visual Studio while your code is running on a Linux server.

What you’ll need

Install dependencies on the Linux test server

Many different distributions of Linux are supported but for this article will assume a fresh install of Ubuntu 16.04 server edition. In order for Visual Studio to remotely connect and debug .NET Core applications the Linux server will require an SSH Server for use by Visual Studio (more on this later) and Unzip and Curl packages installed to allow Visual Studio to install the correct version of the remote debugger.

Log into the Linux test VM and issue the following commands:

sudo apt-get update sudo apt-get install openssh-server unzip curl

Next, install .NET Core SDK on the server:

First, register the Microsoft signature key

curl | gpg --dearmor > microsoft.gpg

sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg

sudo sh -c 'echo "deb [arch=amd64] xenial main" > /etc/apt/sources.list.d/dotnetdev.list'

Next, install the .NET Core SDK 2.0

sudo apt-get update

sudo apt-get install dotnet-sdk-2.0.0

**For updated instructions or additional Linux distributions, see the official installation instructions

Finally, verify the installation by issuing the following command to display the installed version of the .NET Core SDK

dotnet --version

Deploy application to your Linux VM

First, create a new ASP Core application by opening Visual Studio 2017

  1. Create a ASP Core Web Application
  2. Name the project LinuxDebug
  3. Press OK

  1. On the next dialog make sure options are selected
    1. .NET Core framework
    2. ASP Net Core 2.0
    3. Web Application (Model-View-Controller)
    4. Docker support is NOT Checked
    5. Authentication is set to No Authentication
    6. Press OK

The default behavior for Asp Core is to accept requests only from localhost. To change this, modify the program.cs file and add UseUrls(http://*:5000) to the webhost setup

namespace LinuxDebug


public class Program


public static IWebHost BuildWebHost(string[] args) =>







Next, publish the web application to a directory that contains the files needed to run the application on the Linux Test VM.

  1. Right click on the LinuxDebug Project in the Solution Explorer and select Publish Build Rebuild Clean Pack Publish... Bundler & Minfier Overview File Nesting
  2. Choose the Folder as the Publish Method and press Publish After publish change the configuration to Debug by

    1. Selecting Settings
    2. Change configuration to DEBUG
    3. The press Save. A debug build is necessary to step through the code using the remote debugger.
    4. Click Publish
    5. Copy the files from the publish directory (\bin\Debug\PublishOutput\) to a directory with execute permission on the Linux Test VM.

Start the ASP Core Application on the Linux VM

Launch the ASP Core application and make sure everything runs on Linux without errors.

  1. Connect to Linux server using SSH
  2. Navigate to the directory the application was copied to
  3. At the command prompt type

dotnet LinuxDebug.dll

*The Linux operating system is case sensitive so make sure you use the proper case for the name of the dll.

  1. Back on Windows, open up your favorite browser and navigate to the ip address of the Linux server followed by a “:5000” http://<server_ip_address>:5000
  2. After a few seconds you should see your web application.

*If your Linux server has a firewall running you may need to update the rules to allow incoming connections on port 5000

Attach Debugger to ASP Core on Linux

Using Visual Studio running on Windows we will attach the debugger to an ASP Core application running on a remote Linux Server.

First, you will need:

  1. An Asp Core application running on Linux
  2. The IP Address of the Linux Server running application
  3. A user on the Linux server that has permissions to
    1. Log into SSH
    2. Read/Write access to home directory

In Visual Studio, click on the Debug menu item and select Attach To Process

On the Attach To Process Dialog set the following properties

  1. Connection Type = SSH
  2. Connection Target = IP Address of your Linux Test VM (Press ENTER)
  3. Pressing enter on connection type displays the “Connect to Remote System” dialog box
  4. Enter the user name and password for a user that has SSH Access
  5. Press connect and if everything is entered correctly then you will see a list of processes on the Ubuntu server

*If not already installed, Visual Studio will install the remote debugger into the user’s home directory in a subfolder named .vs-debugger

Attach to Process Connection Type: Connection Target: Connection Type Informati SSH (Secure Shell) Transp Attach to: Available Processes P rocess Z] Show processes from Connect to Remote System Use this dialog to connect to Linux, Mac, Windows, or other systems, using SSH. The connection added here can be used later for build or debugging, or in projects that use remote builds. Manage existing connections Find... ke shell (ex: Linux, macOS, etc). Host name: User name: Authentication type: Passwo rd: < username > Passwo rd Connect Cancel Filter Processes r Name Attach Session Refresh Cancel

Make sure the web application is running on the Ubuntu server and look for a process named “dotnet”

  1. Type “dotnet” to only show process names that begin with “dotnet”
  2. Locate the dotnet process running your application
  3. Press Attach

Click “Managed” then click OK

Attach to 'dotnet' - Select Code Type Automatically determine the type of code to debug @ Debug these code types: Managed (.NET Core for u nix) C] Natwe (GD8) Cancel

Task 2: Step through code

  1. Set a break point in the Home controller About action method
  2. Press the about link on the web site
  3. Step through the code running on the Linux server

The debug experience on a remote Linux server is similar to developing on a local Windows server. Visual Studio has excellent support for debugging your applications on Linux machines but it is less than intuitive to setup the first time.


Discussion is closed.

Feedback usabilla icon