-
Notifications
You must be signed in to change notification settings - Fork 219
Offroad Debugging of .NET Core on Linux OSX from Visual Studio
Microsoft and the .NET community have created a new version of .NET, .NET Core, which is designed to be cross-platform, modular, and optimized for the cloud.
If you want to develop on the target device itself, you can use Visual Studio Code by following these instructions. But it is also possible to stay in Visual Studio and still debug to Linux or OSX. For day-to-day development, especially if you intend to deploy to a Linux Docker container, Visual Studio 2017 included tools for publishing and debugging to a Docker container. You can also remotely attach to a process over SSH.
In the future, more scenarios are likely to get a more 'on-road' experience from Visual Studio. But for now, for folks who want to play around with non-Docker scenarios launch, or non-SSH attach or just want to get under the hood and see how things work, this wiki page should walk you through how to get things to work in an offroad manner. Pay attention as this will be a bit bumpy.
The debugger platform has been expanded between Visual Studio 2017 15.3 and previous versions of Visual Studio. Visual Studio can now communicate using the debug adapter protocol which is used by Visual Studio, Visual Studio Code and Visual Studio for Mac. This protocol is now used for debugging cross-platform .NET Core applications. The following instructions apply to Visual Studio 15.3 (and newer). If you are constrained to an older version of Visual Studio refer to the legacy instructions.
File bugs and feature requests here. Many issues are likely to be in common with Visual Studio Code, so please also look in the VS Code C# extension github to see if the issue is already filed.
Install Visual Studio 2017 and select the .NET Core workload.
- Install the .NET Core Command line tools (CLI).
- Install VSDBG by running the following command. Replace '~/vsdbg' with wherever you want vsdbg installed to.
curl -sSL https://aka.ms/getvsdbgsh | bash /dev/stdin -v vs2017u1 -l ~/vsdbg
Visual Studio relies on another executable to take care of remoting stdin/out between the Windows computer and the target computer. The nice side of this is that you can debug as long as you have some way to exchange messages between your two computers; The downside is that this will take a bit of work to setup. Then again, you are reading the offroad instructions :). Here are some hints for getting things setup with Docker or SSH, but you can bring anything you want.
For SSH support, you will first want to enable SSH in your Linux server. For example, on Ubuntu you can do that by running:
sudo apt-get install openssh-server
If you are developing and compiling your app in Visual Studio, you need some way of getting the following on your Linux target machine:
- The PDB files for any module you want to debug. Currently, by default, projects built on Windows will not generate PDBs that are readable on Linux, so you need to change your project to use Portable PDBs (instructions).
- The app itself and any runtime dependencies it might have
- The '<proj-name>.deps.json' file which is used by the 'dotnet' host executable to determine runtime dependencies
For simple projects, you can find these files in <SolutionDir>\artifacts\src\<ProjectName>\bin\Debug\<TargetFramework>. For projects with dependencies, you can use 'dotnet publish' to assemble the files you are likely to need.
If you are compiling your app on Linux, you need some way of sharing sources back to Windows so that Visual Studio can open them. Keep in mind that we don't yet support checks in the debugger to make sure the files match exactly, so make sure you are debugging with the right set of source files.
Obviously there any many options to transfer files between Windows and Linux. This document will not try and list all of them, but for those just trying to kick the tires, here are a few commands you might find useful:
Connect to a Windows share from Ubuntu:
sudo apt-get install cifs-utils
sudo mkdir /mnt/myshare
sudo mount -t cifs //my-windows-computer/myshare /mnt/myshare -o domain=my-windows-domain,username=myalias,uid=$USER,gid=$USER
# /mnt/myshare should now be mapped
To copy files using scp (SSH-based secure copy):
# NOTE: greggm is an example account name
c:\mytools\pscp.exe -i c:\users\greggm\my-ssh-key.ppk c:\MyProject\artifacts\src\MyProject\bin\Debug\netcoreapp1.0\* greggm@mylinuxbox:/home/greggm/myproject
Next, you need to create an launch.json file that will tell Visual Studio how to debug. Here is an example launch.json file which uses plink.exe to connect to the target over SSH and launch a project called 'clicon':
{
"version": "0.2.0",
"adapter": "c:\\mytools\\plink.exe",
"adapterArgs": "-i c:\\users\\greggm\\ssh-key.ppk greggm@mylinuxbox -batch -T ~/vsdbg/vsdbg --interpreter=vscode",
"languageMappings": {
"C#": {
"languageId": "3F5162F8-07C6-11D3-9053-00C04FA302A1",
"extensions": [ "*" ]
}
},
"exceptionCategoryMappings": {
"CLR": "449EC4CC-30D2-4032-9256-EE18EB41B62B",
"MDA": "6ECE07A9-0EDE-45C4-8296-818D8FC401D4"
},
"configurations": [
{
"name": ".NET Core Launch",
"type": "coreclr",
"cwd": "~/clicon",
"program": "bin/Debug/netcoreapp1.0/clicon.dll",
"request": "launch"
}
]
}
Let's look at how this works:
- Adapter: this is the path to the executable that VSCodeDebugAdapterHost will launch that will connect to the target computer, launch vsdbg, and establish that stdin/out connection. Any tools that forward the stdin/stdout from vsdbg on a remote machine can be used.
- AdapterArgs: Any arguments that the executable specified in 'Adapter' takes. In my example, I am telling plink.exe the path to my private SSH key, telling it to connect to my SSH Linux box, and telling it to run executable vsdbg from the '~/vsdbg' directory that I installed it to. If you not using plink, make sure to set any flags that preserve whitespace since the debug adapter protocol relies on the exact byte length of messages.
- LanguageMappings/ExceptionCategoryMapping: Since VSCodeDebugAdapterHost can be used with multiple debug adapters, this provides the debugger information on C#. This just needs to be copied as-is in order for the debugger to properly support language services and exceptions.
- Program: the path, on the Linux computer, to the executable I want to run. Since the debuggee is a .NET Core assembly, vsdbg will automatically run the program with the dotnet host executable.
If you are attempting to debug retail code, you will want to turn off Just My Code through Tools->Options->Debugging in Visual Studio.
- Start Visual Studio
- View->Other Windows->Command Window
- DebugAdapterHost.Launch /LaunchJson:"<path-to-the-launch.json-file-you-saved>"
Use 'Debug->Detach All' to detach from the process. Stop debugging will terminate the process.
If you run into problems getting this to work, you can turn on logging by opening the VS Command Window (View->Other Windows->Command Window), and running: DebugAdapterHost.Logging /On /OutputWindow. This will then send logging messages to the output window.