Remote Debugging a C# or Visual Basic project in Visual Studio

To debug a Visual Studio application that has been deployed on a different computer, install and run the remote tools on the computer where you deployed your app, configure your project to connect to the remote computer from Visual Studio, and then run your app.

Screenshot of remote debugger components.

For information about remote debugging Universal Windows Apps (UWP), see Debug an Installed App Package.

Requirements

The remote debugger is supported on Windows 7 and newer and on versions of Windows Server starting with Windows Server 2008 Service Pack 2. For a complete list of requirements, see Requirements.

Note

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/regions is not recommended and may fail or be unacceptably slow.

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 update of the remote tools for your version of Visual Studio. Earlier remote tools versions aren't compatible with later Visual Studio versions. (For example, if you're using Visual Studio 2019, download the latest update of the remote tools for Visual Studio 2019. In this scenario, don't download the remote tools for Visual Studio 2022.)
  • Download the remote tools with the same architecture as the machine you're installing them on. For example, if you want to debug x86 applications on a remote computer running an x64 operating system, install the x64 remote tools. To debug x86, ARM, or x64 applications on an ARM64 operating system, install the ARM64 remote tools.
Version Link Notes
Visual Studio 2022 Remote tools Compatible with all Visual Studio 2022 versions. Download the version matching your device operating system (x86, x64 (AMD64), or ARM64). On older versions of Windows Server, see Unblock the file download for help with downloading the remote tools.
Visual Studio 2019 Remote tools Remote tools for Visual Studio 2019 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. Download the version matching your device operating system (x86, x64 (AMD64), or ARM64). On older versions of Windows Server, see Unblock the file download for help with downloading the remote tools.
Visual Studio 2017 Remote tools Remote tools for Visual Studio 2017 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. Download the version matching your device operating system (x86, x64 (AMD64), or ARM64). On Windows Server, see Unblock the file download for help with 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 with 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 2019 Remote tools Compatible with all Visual Studio 2019 versions. Download the version matching your device operating system (x86, x64 (AMD64), or ARM64). On Windows Server, see Unblock the file download for help with downloading the remote tools. For the most recent version of the remote tools, open the Visual Studio 2022 doc.
Visual Studio 2017 Remote tools Compatible with all Visual Studio 2017 versions. Download the version matching your device operating system (x86, x64 (AMD64), or ARM64). On Windows Server, see Unblock the file download for help with 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 with 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 or later 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.
  • To debug x64 apps on an ARM64 operating system, run the x64 msvsmon.exe that is installed with the ARM64 remote tools.

Tip

In some scenarios, it can be most efficient to run the remote debugger from a file share. For more information, see Run the remote debugger from a file share.

Set up the remote debugger

  1. 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.

  2. The first time you start the remote debugger (or before you have configured it), the Remote Debugging Configuration wizard appears.

    In most scenarios, choose Next until you get to the Configure the Windows Firewall page of the wizard.

    Screenshot of remote debugger configuration.

    Screenshot of remote debugger configuration.

    If the Windows Web Services API is not installed, which happens only on Windows Server 2008 R2, select the Install button.

  3. 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.

    Next, select Finish to start the remote debugger.

    Next, select Configure remote debugging to start the remote debugger.

  4. When configuration is complete, the Remote Debugger window appears.

    Screenshot of remote debugger window

    Screenshot of remote debugger window

    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:

<Remote debugger installation directory>\msvsmon.exe

Note

If you need to add permissions for additional users, change the authentication mode, or port number for the remote debugger, see Configure the remote debugger.

Remote debug the project

The debugger cannot deploy Visual C# or Visual Basic desktop applications to a remote machine, but you can still debug them remotely as follows. The following procedure assumes that you want to debug it on a computer named MJO-DL, as shown in the illustration below.

  1. Create a WPF project named MyWpf.

    If you are trying to remote debug a MAUI app instead of WPF, see Remote debug a .NET MAUI app on Windows.

  2. Set a breakpoint somewhere in the code that is easily reached.

    For example, you might set a breakpoint in a button handler. To do this, open MainWindow.xaml, and add a Button control from the Toolbox, then double-click the button to open its handler.

  3. In Solution Explorer, right-click the project and choose Properties.

  4. On the Properties page, choose the Debug tab.

    For C# projects targeting .NET Core or .NET 5+, starting in Visual Studio 2022, choose the Debug launch profiles UI from the Debug tab to configure settings for remote debugging.

    Screenshot of the Debug launch profile UI in the Visual Studio Project Properties for C# and .NET.

    Otherwise, you change remote debug settings directly in the Debug tab.

    Screenshot of the Debug tab in the Visual Studio Project Properties. The Use remote machine property is set to 'MJO-DL:4022'.

  5. Make sure the Working directory text box is empty.

  6. Choose Use remote machine, and type yourmachinename:port in the text box. (The port number is shown in the remote debugger window. The port number increments 2 in each version of Visual Studio).

    In this example, use:

    MJO-DL:4026 on Visual Studio 2022

    MJO-DL:4024 on Visual Studio 2019

  7. Make sure that Enable native code debugging is not selected.

  8. Build the project.

  9. Create a folder on the remote computer that is the same path as the Debug folder on your Visual Studio computer: <source path>\MyWPF\MyWPF\bin\Debug.

  10. Copy the executable that you just built from your Visual Studio computer to the newly created folder on the remote computer.

    Caution

    Do not make changes to the code or rebuild (or you must repeat this step). The executable you copied to the remote machine must exactly match your local source and symbols.

    You can copy the project manually, use XCopy, Robocopy, PowerShell, or other options.

  11. Make sure the remote debugger is running on the target machine (If it's not, search for Remote Debugger in the Start menu). The remote debugger window looks like this.

    Screenshot of remote debugger window for VS 2022.

    Screenshot of remote debugger window for VS 2019.

  12. In Visual Studio, start debugging (Debug > Start Debugging, or F5).

  13. If prompted, enter network credentials to connect to the remote machine.

    The required credentials vary depending on your network's security configuration. For example, on a domain computer, you can enter your domain name and password. On a non-domain machine, you might enter the machine name and a valid user account name, like MJO-DL\name@something.com, along with the correct password.

    You should see that the WPF application's main window is open on the remote computer.

  14. If necessary, take action to hit the breakpoint. You should see that the breakpoint is active. If it isn't, the symbols for the application haven't loaded. Retry, and if that doesn't work, get information about loading symbols and how to troubleshoot them at Understanding symbol files and Visual Studio's symbol settings.

  15. On the Visual Studio machine, you should see that execution has stopped at the breakpoint.

    If you have any non-code files that need to be used by the application, you need to include them in the Visual Studio project. Create a project folder for the additional files (in the Solution Explorer, click Add > New Folder). Then add the files to the folder (in the Solution Explorer, click Add > Existing Item, then select the files). On the Properties page for each file, set Copy to Output Directory to Copy always.

Remote debug a .NET MAUI app on Windows

.NET MAUI apps are packaged apps that need to be registered when deployed, not just copied to a remote machine. To remote debug, you can deploy an unpackaged version of the app.

Use one of the following methods to remote debug:

  • Publish the app to the remote device as an unpackaged app using the steps described in Use the CLI to publish unpackaged .NET MAUI apps for Windows, and then follow the steps in this article to remote debug. (Skip the steps to copy the app.)

  • Follow the steps in this article, including steps to create a Debug Launch profile for the project. Before you start debugging, manually edit the launchSettings.json file, replacing the commandName Project value with MsixPackage, as shown here.

    "Remote Profile": {
      "commandName": "MsixPackage",
      "remoteDebugEnabled": true,
      "remoteDebugMachine": "170.200.20.22",
      "authenticationMode": "None"
    }
    

    When you start debugging, this method first deploys an unpackaged version of the app and starts it.

    Note

    You can't edit launchSettings.json in the Debug Launch profile dialog box once you change the value to MsixPackage.

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.

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).