Last month, Microsoft announced the release of Visual Studio for Mac: a full-featured development environment to help developers on the Mac create apps, games, and services for mobile, cloud, and web.
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 debug 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. As of Visual Studio 2019 version 16.3, Docker attach support is also included with Visual Studio.
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/Docker 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.
Your feedback
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 OmniSharp C# extension GitHub to see if the issue is already filed.
Machine setup
Visual Studio Computer
Install Visual Studio 2017 or newer and select the .NET Core workload. If you already have Visual Studio, you can do this from within the installer.
Linux Computer
The Linux system needs to have the .NET CLI tools,
dotnet
, and a vsdbg
debugger installed.- Install the .NET Core Command line tools (CLI).
- Install VSDBG by running the following command. Replace '~/vsdbg' with wherever you want vsdbg installed to.
Copying vsdbg
from Windows to Linux using PowerShell
If you want to download vsdbg on Windows and then copy it to your Linux/Mac computer/container, you can use the .ps1 script with this one-liner. Other supported
RuntimeID
values are linux-musl-x64
, linux-arm
and osx
.powershell -NoProfile -ExecutionPolicy unrestricted -Command '[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; &([scriptblock]::Create((Invoke-WebRequest -useb 'https://aka.ms/getvsdbgps1'))) -Version vs2017u5 -RuntimeID linux-x64 -InstallPath c:vsdbglinux-x64'
Setting up a transport
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.
SSH
For SSH support, you will first want to enable SSH in your Linux server. For example, on Ubuntu you can do that by running:
Then, on Windows you need an SSH client designed to be used programmatically. Plink.exe from PuTTY fits the bill, though you can certainly use other tools too. If you are running on a recent version of Windows 10, you can use the built-in ssh.exe (
C:WindowssysnativeOpenSSHssh.exe
). Note: Using C:WindowsSystem32
will not work as expected.Next, you need a scriptable way to authenticate. One option is to provide the password on the command line, but obviously there are some security concerns there. A more secure option is to use SSH keys --
- Download puttygen.exe from PuTTY.
- Run the tool and click 'Generate' and follow the instructions. Note: leave 'Key passphrase' empty, otherwise plink.exe will fail to open the key.
- Save the generated private key to a file.
- Copy the public key's text from the top part of the PuTTY Key Generator's Window.
- Add this to the ~/.ssh/authorized_keys file on your server.
- Test your connection from the command line. This will also allow you to accept the server's key on the client, which must be done the first time.
Example:
Sharing sources and compiled binaries
Building on Windows
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. Note that only Portable PDBs are supported.
- 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>artifactssrc<ProjectName>binDebug<TargetFramework>. For projects with dependencies, you can use 'dotnet publish' to assemble the files you are likely to need.
Building on Linux
Qemu vga drivers for mac. 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.
Transferring file
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:
To copy files using scp (SSH-based secure copy):
Create launch configuration file:
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':
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. The
-T
flags disables PTY allocation, which is important for byte length. Be sure to use-T
and not-t
. - 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.
Turn off Just My Code if you are retail debugging
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 debugging
- Start Visual Studio
- View->Other Windows->Command Window
- DebugAdapterHost.Launch /LaunchJson:'<path-to-the-launch.json-file-you-saved>' /EngineGuid:541B8A8A-6081-4506-9F0A-1CE771DEBC04
Troubleshooting
- 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 ('Debug Adapter Host Log' pane). You can also add/Verbosity:debug
for more information. - The error message 'The debug adapter exited unexpectedly' means that the transport executable (plink.exe in the above example) exited unexpectedly. A few notes in troubleshooting this --
- As noted in the first troubleshooting step, the logs are the first place to look. The transport may have written errors before it exited (
Debug adapter error output:
lines). - If the target process is running in a Docker container, this could indicate that the container shutdown. For example because the additional memory used by the debugger caused the container to hit its memory limit.
- This could also indicate that vsdbg running in the container is crashing or being aborted. You can confirm or deny this by modifying the transport command line to run a script that would run vsdbg and then output vsdbg's exit code.
- As noted in the first troubleshooting step, the logs are the first place to look. The transport may have written errors before it exited (
Detaching
Use 'Debug->Detach All' to detach from the process. Stop debugging will terminate the process.
Attaching
Instead of launching, it is also possible to attach in a similar way. Here is an example launch.json file that attaches to a process running in a Docker container:
Notes:
- Docker support is now built in to the Attach To Process dialog, so use this as a starting point if you need to use a custom transport (example: kubernetes). But please don't actually use this for Docker any longer.
- This requires that vsdbg is installed to the container. In this case it assumes it is installed to the
/remote_debugger
folder (see 'adapterArgs' line above). See the Linux Computer section for more information on obtaining vsdbg.
You can debug a Visual Studio application that has been deployed on a different computer. To do so, you use the Visual Studio remote debugger.
For in-depth instructions on remote debugging, see these topics.
Scenario | Link |
---|---|
Azure App Service | Snapshot Debugger or Remote debug ASP.NET on Azure |
Azure VM | Remote debug ASP.NET on Azure |
Azure Service Fabric | Debug an Azure Service Fabric application |
ASP.NET | Remote debug ASP.NET Core or Remote Debug ASP.NET |
C# or Visual Basic | Remote debug a C# or Visual Basic project |
C++ | Remote debug a C++ project |
Universal Windows Apps (UWP) | Run UWP apps on a remote machine or Debug an installed app package |
If you just want to download and install the remote debugger and don't need any additional instructions for your scenario, follow the steps in this article.
Download and Install the remote tools
On the remote device or server that you want to debug on, rather than the Visual Studio machine, download and install the correct version of the remote tools from the links in the following table.
- Download the most recent remote tools for your version of Visual Studio. The latest remote tools version is compatible with earlier Visual Studio versions, but earlier remote tools versions aren't compatible with later Visual Studio versions. (For example, if you are using Visual Studio 2017, download the latest update of the remote tools for Visual Studio 2017. In this scenario, do not download the remote tools for Visual Studio 2019.)
- Download the remote tools with the same architecture as the machine you're installing them on. For example, if you want to debug a 32-bit app on a remote computer running a 64-bit operating system, install the 64-bit remote tools.
Version | Link | Notes |
---|---|---|
Visual Studio 2019 | Remote tools | Compatible with all Visual Studio 2019 versions. Download the version matching your device operating system (x86, x64, or ARM64). On Windows Server, see Unblock the file download for help downloading the remote tools. |
Visual Studio 2017 | Remote tools | Compatible with all Visual Studio 2017 versions. Download the version matching your device operating system (x86, x64, or ARM64). On Windows Server, see Unblock the file download for help downloading the remote tools. |
Visual Studio 2015 | Remote tools | Remote tools for Visual Studio 2015 are available from My.VisualStudio.com. If prompted, join the free Visual Studio Dev Essentials program, or sign in with your Visual Studio subscription ID. On Windows Server, see Unblock the file download for help downloading the remote tools. |
Visual Studio 2013 | Remote tools | Download page in Visual Studio 2013 documentation |
Visual Studio 2012 | Remote tools | Download page in Visual Studio 2012 documentation |
Version | Link | Notes |
---|---|---|
Visual Studio 2017 | Remote tools | Compatible with all Visual Studio 2017 versions. Download the version matching your device operating system (x86, x64, or ARM64). On Windows Server, see Unblock the file download for help downloading the remote tools. For the most recent version of the remote tools, open the Visual Studio 2019 doc. |
Visual Studio 2015 | Remote tools | Remote tools for Visual Studio 2015 are available from My.VisualStudio.com. If prompted, join the free Visual Studio Dev Essentials program, or sign in with your Visual Studio subscription ID. On Windows Server, see Unblock the file download for help downloading the remote tools. |
Visual Studio 2013 | Remote tools | Download page in Visual Studio 2013 documentation |
Visual Studio 2012 | Remote tools | Download page in Visual Studio 2012 documentation |
You can run the remote debugger by copying msvsmon.exe to the remote computer, rather than installing the remote tools. However, the Remote Debugger Configuration Wizard (rdbgwiz.exe) is available only when you install the remote tools. You may need to use the wizard for configuration if you want to run the remote debugger as a service. For more information, see (Optional) Configure the remote debugger as a service.
Note
- To debug Windows 10 apps on ARM devices, use ARM64, which is available with the latest version of the remote tools.
- To debug Windows 10 apps on Windows RT devices, use ARM, which is available only in the Visual Studio 2015 remote tools download.
Requirements
Supported Operating Systems
The remote computer must be running one of the following operating systems:
- Windows 10 (not phone)
- Windows 8 or 8.1 (not phone)
- Windows 7 Service Pack 1
- Windows Server 2016
- Windows Server 2012 or Windows Server 2012 R2
- Windows Server 2008 Service Pack 2, Windows Server 2008 R2 Service Pack 1
Note
Windows Phone requires a USB connection to debug (it does not require the remote tools).
Supported Hardware Configurations
- 1.6 GHz or faster processor
- 1 GB of RAM (1.5 GB if running on a virtual machine)
- 1 GB of available hard disk space
- 5400-RPM hard drive
- DirectX 9-capable video card running at 1024 x 768 or higher display resolution
Network configuration
The remote computer and the Visual Studio computer must be connected over a network, workgroup, or homegroup, or else connected directly through an Ethernet cable. Debugging between two computers connected through a proxy is not supported. Debugging over a high latency or low bandwidth connection, such as dialup Internet, or over the Internet across countries is not recommended and may fail or be unacceptably slow.
(Optional) To run the remote debugger from a file share
You can find the remote debugger (msvsmon.exe) on a computer with Visual Studio Community, Professional, or Enterprise already installed. For some scenarios, the easiest way to set up remote debugging is to run the remote debugger (msvsmon.exe) from a file share. For usage limitations, see the remote debugger's Help page (Help > Usage in the remote debugger).
- Find msvsmon.exe in the directory matching your version of Visual Studio:Program Files (x86)Microsoft Visual Studio2019EnterpriseCommon7IDERemote Debuggerx86msvsmon.exeProgram Files (x86)Microsoft Visual Studio2019EnterpriseCommon7IDERemote Debuggerx64msvsmon.exeProgram Files (x86)Microsoft Visual Studio2017EnterpriseCommon7IDERemote Debuggerx86msvsmon.exeProgram Files (x86)Microsoft Visual Studio2017EnterpriseCommon7IDERemote Debuggerx64msvsmon.exe
- Share the Remote Debugger folder on the Visual Studio computer.
- On the remote computer, run msvsmon.exe from the shared folder. Follow the setup instructions.
Tip
For command line installation and command line reference, see the Help page for msvsmon.exe by typing
msvsmon.exe /?
in the command line on the computer with Visual Studio installed (or go to Help > Usage in the remote debugger).Set up the remote debugger
- On the remote computer, find and start the Remote Debugger from the Start menu.If you don't have administrative permissions on the remote computer, right-click the Remote Debugger app and select Run as administrator. Otherwise, just start it normally.If you are planning to attach to a process which is running as an administrator, or is running under a different user account (such as IIS), right-click the Remote Debugger app and select Run as administrator. For more information, see Run the remote debugger as an administrator.
- The first time you start the remote debugger (or before you have configured it), the Remote Debugging Configuration dialog box appears.
- If the Windows Web Services API is not installed, which happens only on Windows Server 2008 R2, select the Install button.
- Select at least one network type you want to use the remote tools on. If the computers are connected through a domain, you must choose the first item. If the computers are connected through a workgroup or homegroup, choose the second or third item as appropriate.
- Select Configure remote debugging to configure the firewall and start the remote debugger.
- When configuration is complete, the Remote Debugger window appears.The remote debugger is now waiting for a connection. Use the server name and port number shown to set the remote connection configuration in Visual Studio.
To stop the remote debugger, select File > Exit. You can restart it from the Start menu, or from the command line:
Configure the remote debugger
You can change some aspects of the configuration of the remote debugger after you have started it for the first time.
- If you need to add permissions for other users to connect to the remote debugger, choose Tools > Permissions. You must have administrator privileges to grant or deny permissions.ImportantYou can run the remote debugger under a user account that differs from the user account you are using on the Visual Studio computer, but you must add the different user account to the remote debugger's permissions.Alternatively, you can start the remote debugger from the command line with the /allow <username> parameter: msvsmon /allow <username@computer>.
- If you need to change the Authentication mode or the port number, or specify a timeout value for the remote tools: choose Tools > Options.For a listing of the port numbers used by default, see Remote Debugger Port Assignments.WarningYou can choose to run the remote tools in No Authentication mode, but this mode is strongly discouraged. There is no network security when you run in this mode. Choose the No Authentication mode only if you are sure that the network is not at risk from malicious or hostile traffic.
(Optional) Configure the remote debugger as a service
For debugging in ASP.NET and other server environments, you must either run the remote debugger as an Administrator or, if you want it always running, run the remote debugger as a service.
Introduction to wasabi client for mac. If you want to configure the remote debugger as a service, follow these steps.
- Find the Remote Debugger Configuration Wizard (rdbgwiz.exe). (This is a separate application from the Remote Debugger.) It is available only when you install the remote tools. It is not installed with Visual Studio.
- Start running the configuration wizard. When the first page comes up, click Next.
- Check the Run the Visual Studio 2015 Remote Debugger as a service checkbox.
- Add the name of the user account and password.You may need to add the Log on as a service user right to this account (Find Local Security Policy (secpol.msc) in the Start page or window (or type secpol at a command prompt). When the window appears, double-click User Rights Assignment, then find Log on as a service in the right pane. Double-click it. Add the user account to the Properties window and click OK). Click Next.
- Select the type of network that you want the remote tools to communicate with. At least one network type must be selected. If the computers are connected through a domain, you should choose the first item. If the computers are connected through a workgroup or homegroup, you should choose the second or third items. Click Next.
- If the service can be started, you will see You have successfully completed the Visual Studio Remote Debugger Configuration Wizard. If the service cannot be started, you will see Failed to complete the Visual Studio Remote Debugger Configuration Wizard. The page also gives some tips to follow to get the service to start.
- Click Finish.At this point the remote debugger is running as a service. You can verify this by going to Control Panel > Services and looking for Visual Studio 2015 Remote Debugger.You can stop and start the remote debugger service from Control Panel > Services.
Set up debugging with remote symbols
You should be able to debug your code with the symbols you generate on the Visual Studio computer. The performance of the remote debugger is much better when you use local symbols. If you must use remote symbols, you need to tell the remote debugging monitor to look for symbols on the remote machine.
Starting in Visual Studio 2013 Update 2, you can use the following msvsmon command-line switch to use remote symbols for managed code:
Msvsmon /FallbackLoadRemoteManagedPdbs
For more information, please see the remote debugging help (press F1 in the remote debugger window, or click Help > Usage). You can find more information at .NET Remote Symbol Loading Changes in Visual Studio 2012 and 2013