-
Notifications
You must be signed in to change notification settings - Fork 218
Offroad Debugging of .NET Core on Linux OSX from Visual Studio Legacy Instructions
The debugger platform has been expanded between Visual Studio 2017 15.3 and older versions of Visual Studio. These legacy instructions are for version of Visual Studio older than 15.3. The current instructions are here.
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 (see MSDN).
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.
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 Web workload.
- Install the .NET Core Command line tools (CLI).
- Install CLRDBG by running the following command. Replace '~/clrdbg' with wherever you want clrdbg installed to.
curl -sSL https://aka.ms/getclrdbgsh | bash /dev/stdin -v vs2015u2 -l ~/clrdbg
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.
If your target is running in Docker, you want to install the Docker Toolbox, and configure the Docker client tools to connect to whatever host machine is running your container.
Test to make sure you have things setup correctly by running something like:
REM List the containers so you know which one to target
"C:\Program Files\Docker Toolbox\docker.exe" ps
"C:\Program Files\Docker Toolbox\docker.exe" exec -i <container-id> /bin/bash -c "echo hello world"
REM 'hello world' should print
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\netcoreapp1.0. 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 XML file that will tell Visual Studio how to debug. You may want to save https://github.com/Microsoft/MIEngine/blob/master/src/MICore/LaunchOptions.xsd to your project so that the XML editor will give you IntelliSense for the file. Here is an example launch option file which uses plink.exe to connect to the target over SSH and launch a project called 'clicon':
<?xml version="1.0" encoding="utf-8" ?>
<PipeLaunchOptions xmlns="http://schemas.microsoft.com/vstudio/MDDDebuggerOptions/2014"
PipePath="c:\mytools\plink.exe" PipeArguments="-i c:\users\greggm\ssh-key.ppk greggm@mylinuxbox -batch -t ~/clrdbg/clrdbg --interpreter=mi"
TargetArchitecture="x64" MIMode="clrdbg" ExePath="dotnet" WorkingDirectory="~/clicon" ExeArguments="bin/Debug/netcoreapp1.0/MyExmapleApp.dll">
</PipeLaunchOptions>
Let's look at how this works:
- PipePath: this is the path to the executable that MIEngine will launch that will connect to the target computer, launch clrdbg, and establish that stdin/out connection. If you are using Docker, you want this set to 'C:\Program Files\Docker Toolbox\docker.exe' (or wherever the Docker client tools are installed).
- PipeArguments: Any arguments that the executable specified in 'PipePath' 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 clrdbg from the '~/clrdbg' directory that I installed it to. If I was using Docker, I might set this to 'exec -i ~/clrdbg/clrdbg --interpreter=mi'.
- ExePath: the path, on the Linux computer, to the executable I want to run. .NET Core provides a generic host executable ('dotnet') which the installer adds to the path. So as long as your application uses the default 'dotnet' host executable, you can leave this as-is.
- ExeArguments: If you are using the 'dotnet' host executable, the first argument is the path to the dll you want to run. After that you can include any command line arguments that your executable accepts.
As of VS 2017, you no longer need to use pipe launch options for SSH. Instead you can use this builtin SSH support like this:
<?xml version="1.0" encoding="utf-8" ?>
<SSHLaunchOptions xmlns="http://schemas.microsoft.com/vstudio/MDDDebuggerOptions/2014"
TargetMachine="169.254.2.3"
TargetArchitecture="x64" MIMode="clrdbg" ExePath="dotnet" WorkingDirectory="~/clicon" ExeArguments="bin/Debug/netcoreapp1.0/MyExmapleApp.dll">
</SSHLaunchOptions>
You can also use launch option files to attach to the target process. For example, here is how to attach to process id #13594 with a clrdbg installed to ~/clrdbg:
<PipeLaunchOptions xmlns="http://schemas.microsoft.com/vstudio/MDDDebuggerOptions/2014"
PipePath="c:\mytools\plink.exe" PipeArguments="-i c:\users\greggm\my-ssh-key.ppk greggm@mylinuxbox -batch -t ~/clrdbg/clrdbg --interpreter=mi"
TargetArchitecture="x64" MIMode="clrdbg" ProcessId="13594">
<LaunchCompleteCommand>None</LaunchCompleteCommand>
</PipeLaunchOptions>
If you are attempting to debug retail code, you will want to turn off Just My Code through Tools->Options->Debugging in Visual Studio. MIEngine has some issues doing this on the fly still, so I would recommend doing it before start debugging.
- Start Visual Studio
- View->Other Windows->Command Window
- Debug.MIDebugLaunch /Executable:dotnet /OptionsFile:<path-to-the-xml-file-you-saved>
Use 'Debug->Detach All' to detach from the process. Stop debugging will terminate the process. SSH AttachSSH Attach