Remote Debug Support in Visual Studio 2019

Lisbeth Cardoso Guerra

Lisbeth

Visual Studio 2019 offers remote debug support for MSBuild and CMake projects targeting Windows and Linux. Thanks to remote debugging, the following scenarios and more are now possible:

  • Debugging on your production machines with no development tools installed other than the remote debugger tools.
  • Targeting developer environments that you do not use daily (i.e., less common operating systems or software configurations).
  • Targeting environments where Visual Studio is unavailable (i.e., ARM64 machines, or unsupported operating system versions).

To guarantee a seamless remote debugging experience for users, you need some additional dependencies to be copied to the target machine. Luckily, we do that for you and automatically deploy these dependencies alongside the built binaries from your project we deem as needed for debugging. In Windows scenarios specifically, we automatically deploy the Universal CRT library (debug only, as the release version ships with the Windows operating system) as well as VCRuntime libraries which are necessary to run and debug binaries in environments where these libraries are not available on the system.

For step-by-step instructions of the various remote debug workflows, check out the following tutorials:

Remote Debug a C++ Project – Visual Studio | Microsoft Docs

Deploy, run, and debug your Linux MSBuild C++ project in Visual Studio | Microsoft Docs

Tutorial: Debug a CMake project on a remote Windows machine | Microsoft Docs

Configure CMake debugging sessions in Visual Studio | Microsoft Docs

Note: Although with Visual Studio 2019 you can create MSBuild and CMake projects targeting Linux and Windows, CMake is encouraged for Linux development because the same project files can be used in both platforms.

User Customizability of Remote Deploy

Whether you are targeting Windows or Linux, or using MSBuild or CMake, Visual Studio offers you the flexibility to customize your deployment. We will cover some of these in the sub-sections below.

MSBuild Projects targeting Windows

You can deploy and debug MSBuild projects targeting a remote Windows machine very easily in Visual Studio 2019. In the Property Pages, within the Debugging tab, you will need to specify Remote Command, Working Directory, Remote Server Name and Deployment Directory properties as a minimum. If you want to deploy additional files, you will have to specify them in the Additional Files to Deploy property.

The "Deploy Visual C++ Runtime Libraries" option highlighted and set to Yes

Visual Studio 2019 allows you to specify both debug and release versions of the runtime libraries. To do so, you must set the Deploy Visual C++ Debug Runtime Libraries and Deploy Visual C++ Runtime Libraries properties to Yes.

Once your configuration is set, Visual Studio will take care of deploying all the files (including the ucrt and vcruntime libraries needed) to your remote machine.

MSBuild Projects targeting Linux

When targeting Linux using MSBuild project, you can specify a different machine from your build machine (the default) to deploy to and debug on, as shown below:

The Remote Debug Machine setting set with a username, port, and authentication method

By default, only the files necessary for the process to debug will be deployed to the remote debug machine. However, in some cases, you may want more control over your project’s deployment. In these cases, you can append the code MSBuild elements below to your .vcxproj file, making sure to specify the actual source and target paths you want:

<ItemGroup> 
   <RemoteDeploy Include="__example.cpp"> 
<!-- This is the source Linux machine, can be empty if DeploymentType is LocalRemote --> 
      <SourceMachine>$(RemoteTarget)</SourceMachine> 
      <TargetMachine>$(RemoteDebuggingTarget)</TargetMachine> 
      <SourcePath>~/example.cpp</SourcePath> 
      <TargetPath>~/example.cpp</TargetPath> 
<!-- DeploymentType can be LocalRemote, in which case SourceMachine will be empty and SourcePath is a local file on Windows --> 
      <DeploymentType>RemoteRemote</DeploymentType> 
<!-- Indicates whether the deployment contains executables --> 
      <Executable>true</Executable> 
   </RemoteDeploy> 
</ItemGroup>

You can also specify additional source files in your solution that you want deployed if you: right-click on the source file in solution explorer > select properties > set the Content property to “yes”.

CMake Projects targeting Windows

Visual Studio 2019 has support for deploying CMake projects to a remote Windows machine and debugging them with the Visual Studio remote tools. You can specify the type and remoteMachineName properties within the launch.vs.json file.

"configurations": [ 
   { 
      "type": "remoteWindows", 
      "project": "CMakeLists.txt", 
      "projectTarget": "CMakeProject.exe (CMakeProject\\CMakeProject.exe)", 
      "name": "CMakeProject.exe (CMakeProject\\CMakeProject.exe)", 
      "remoteMachineName": "[remote machine’s IP address]: [remote machine’s port number]", 
      "deployDebugRuntimeLibraries": true, 
      "deployRuntimeLibraries": true, 
      "deployDirectory": "~/foo", 
      "disableDeploy": true, 
   } 
]

Visual Studio 2019 allows you to specify both debug and release versions of the runtime libraries. To do so, you must set the deployDebugRuntimeLibraries and deployRuntimeLibraries properties to true.

The contents of the project outputs will be deployed automatically to C:\Windows Default Deploy Directory\<targetname> in the remote machine. If you want to specify a different location, you can set it up in the deployDirectory property. If you do not want to deploy files at all, you can set disableDeploy to true.

In addition, you can specify individual additional files or entire directories you want to deploy each time in case there are some external source/content files you want to be deployed. To do this, you add the following block to your launch.vs.json (make sure you replace example.cpp/exampleDirectory with the actual path to your file/directory):

"deploy": [ 
   { 
      "sourcePath": "~/example.cpp", 
      "targetPath": "~/test/example.cpp", 
   }, 
   { 
      "sourcePath": "~/exampleDirectory", 
      "targetPath": "~/test/exampleDirectory", 
   }, 
]

CMake Projects targeting Linux

When targeting Linux using CMake, you can specify a different machine from your build machine (the default) to deploy to and debug on. To do this, just set the remoteMachineName json filed to one of the established connections in the Connection Manager (IntelliSense will populate the list of all the available options).

You can also customize the deploy location on the target machine by setting the deployDirectory property in launch.vs.json to the intended directory.

In addition, if you want complete control over your deployment, you can append the following code block in your launch.vs.json file. For example:

"deploy": [ 
   { 
      "sourceMachine": "127.0.0.1 (username=example1, port=22, authentication=Password)", 
      "targetMachine": "192.0.0.1 (username=example2, port=22, authentication=Password)", 
      "sourcePath": "~/example.cpp", 
      "targetPath": "~/example.cpp", 
      "executable": "false" 
   } 
]

Give us your feedback

Download the latest Visual Studio 2019 Preview today and give it a try. We’d love to hear from you to help us prioritize and build the right features for you. We can be reached via the comments below, Developer Community, and Twitter (@VisualC). The best way to file a bug or suggest a feature is via Developer Community.

Authors

Moyo Okeremi and Lisbeth Cardoso Guerra.

2 comments

Leave a comment

  • Avatar
    Chris Guzak (WINDOWS)Microsoft employee

    Great to see remote debugging getting improvements. I depend on this a lot so appreciate the attention.

    Some issues I notice regularly in the “Remote Windows Debugger” page.
    – The default for “Remote Server Name” is $(COMPUTERNAME), that is the local machine and does not make sense as a debug target. I use $(DEBUG_TARGET) to identify the machine I want to debug on (my scripts set this before launching VS). Consider adopt something similar to stream line the workflows.
    – “Working Directory” defaults to $(ProjectDir), a folder that is unlikely to exist on the debug target. C:\ seems better, but now that you have a deployment dir consider that.