Debugging ASP Core on Linux with Visual Studio 2017
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
- A Linux Virtual Machine running Ubuntu 16.04 server – GUI not required. For a complete list of supported Linux Distributions please see https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x
- Windows Developer Laptop with:
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 https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
sudo mv microsoft.gpg /etc/apt/trusted.gpg.d/microsoft.gpg
sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-ubuntu-xenial-prod 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
Deploy application to your Linux VM
First, create a new ASP Core application by opening Visual Studio 2017
- Create a ASP Core Web Application
- Name the project LinuxDebug
- Press OK
- On the next dialog make sure options are selected
- .NET Core framework
- ASP Net Core 2.0
- Web Application (Model-View-Controller)
- Docker support is NOT Checked
- Authentication is set to No Authentication
- 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
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.
- Right click on the LinuxDebug Project in the Solution Explorer and select Publish
- Choose the Folder as the Publish Method and press Publish
After publish change the configuration to Debug by
- Selecting Settings
- Change configuration to DEBUG
- The press Save. A debug build is necessary to step through the code using the remote debugger.
- Click Publish
- 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.
- Connect to Linux server using SSH
- Navigate to the directory the application was copied to
- At the command prompt type
*The Linux operating system is case sensitive so make sure you use the proper case for the name of the dll.
- 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
- 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:
- An Asp Core application running on Linux
- The IP Address of the Linux Server running application
- A user on the Linux server that has permissions to
- Log into SSH
- 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
- Connection Type = SSH
- Connection Target = IP Address of your Linux Test VM (Press ENTER)
- Pressing enter on connection type displays the “Connect to Remote System” dialog box
- Enter the user name and password for a user that has SSH Access
- 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
Make sure the web application is running on the Ubuntu server and look for a process named “dotnet”
- Type “dotnet” to only show process names that begin with “dotnet”
- Locate the dotnet process running your application
- Press Attach
Click “Managed” then click OK
- Set a break point in the Home controller About action method
- Press the about link on the web site
- 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.