Run UWP apps on a remote machine in Visual Studio

To run a UWP app on a remote machine, you must attach to it using the Remote Tools for Visual Studio. The remote tools enable you to run, debug, profile, and test a UWP app that is running on one device from a second computer that is running Visual Studio. Running on a remote device can be especially effective when the Visual Studio computer does not support functionality that is specific to UWP apps, such as touch, geo-location, and physical orientation. This topic describes the procedures to configure and start a remote session.

In some scenarios, the remote tools are automatically installed when you deploy to a remote device.

  • For Windows 10 PCs running Creators Update and later versions, remote tools will be installed automatically.
  • For Windows 10 Xbox, IOT, and HoloLens devices, remote tools will be installed automatically.
  • For Windows Mobile 10, you must be physically connected to the phone, you must enable developer mode and you must select Device as the debug target. Remote tools are not required or supported.

For Windows 10 PCs running a pre-Creator's Update version of Windows, you must install the remote tools on the remote machine manually before you can debug. Follow the instructions in this topic.

Prerequisites

To debug on a remote device:

  • The remote device and the Visual Studio computer must be connected over a network or connected directly through a USB or Ethernet cable. Debugging over the internet is not supported.

  • You must enable developer mode.

  • For Windows 10 PCs running a version of Windows 10 earlier than Windows 10 Creator's Update, you must install and run the remote debugging components.

Security

By default, Universal (Unencrypted Protocol) is used on Windows 10. Ths protocol should only be used on trusted networks. The debugging connection is vulnerable to malicious users who could intercept and change data being passed between the development and remote machine.

Warning

There is no network security when you set the authentication mode to Universal (Unencrypted Protocol) or None. Choose these modes only if you are sure that the network is not at risk of from malicious or hostile traffic.

How to connect directly using a USB cable

On Windows 10, you can deploy to a USB-connected device by choosing Device instead of Remote Machine as the deployment target (you can do this in the Standard toolbar or in the debugging properties page).

Configure the Visual Studio project for remote debugging

You specify the remote device to connect to in the properties of the project. The procedure differs depending on the programming language. You can type the network name of the remote device or you can select it from the Remote Connection dialog box.

Select Remote Debugger Connection dialog box

The dialog box lists only those devices that are on the local subnet of the Visual Studio computer and that are running the remote debugger.

Tip

If you have trouble connecting to a remote device, try entering the IP address of the device. To determine the IP address of a device, open a command window and then type ipconfig. The IP address is listed as IPv4 Address.

Choose the remote device for C# and Visual Basic projects

  1. Select the project name in Solution Explorer and then choose Properties from the shortcut menu.

  2. Select Debug.

  3. Choose Remote Machine from the Target Device list.

  4. Enter the network name of the remote device in the Remote Machine box or choose Find to choose the device from the Select Remote Debugger Connection dialog box.

    Managed project properties for remote debugging

Choose the remote device for JavaScript and C++ projects

  1. Select the project name in Solution Explorer and then choose Properties from the shortcut menu.

  2. Expand the Configuration Properties node and then select Debugging.

  3. Choose Remote Debugger from the Debugger to launch list.

  4. Enter the network name of the remote device in the Machine Name box or choose the down arrow in the box to choose the device from the Select Remote Debugger Connection dialog box.

    C++ project properties for remote debugging

Download and Install the remote tools (pre-Creators Update)

If you are using a pre-Creator's Update versions of Windows 10, then follow these instructions. Otherwise, you can skip this section.

  1. On the device or server machine that you want to debug (rather than the machine running Visual Studio), get the correct version of the remote tools.

    Version Link Notes
    Visual Studio 2017 version 15.5 Remote tools Always download the version matching your device operating system (x86 or x64). If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted.
    Visual Studio 2017 (older) Remote tools Remote tools for earlier releases of Visual Studio 2017 are available from My.VisualStudio.com. If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted.
    Visual Studio 2015 Update 3 Remote tools If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted.
    Visual Studio 2015 (older) Remote tools If prompted, join the free Visual Studio Dev Essentials group, or sign in with your Visual Studio subscription ID. If enhanced security mode is enabled (Windows Server), you must add new trusted sites if prompted.
    Visual Studio 2013 Remote tools Download page in Visual Studio 2013 documentation
    Visual Studio 2012 Remote tools Download page in Visual Studio 2012 documentation
  2. On the download page, choose the version of the tools that matches your operating system (x86, x64, or ARM) and download the remote tools.

    Important

    We recommend you install the most recent version of the remote tools that matches your version of Visual Studio. Mismatched versions are not recommended. In addition, you must install the remote tools that have the same architecture as the operating system on which you want to install it. In other words, if you want to debug a 32-bit application on a remote computer running a 64-bit operating system, you must install the 64-bit version of the remote tools on the remote computer.

    Surface 3 switched from ARM to x64 architecture. An ARM version of the remote tools is not available for Visual Studio 2017. For Visual Studio 2015, find the ARM version in the Visual Studio 2015 RTW download.

  3. When you have finished downloading the executable, go to the next section and follow setup instructions.

If you try to copy the remote debugger (msvsmon.exe) to the remote computer and run it, be aware that the Remote Debugger Configuration Wizard (rdbgwiz.exe) is installed only when you download the tools. You may need to use the wizard for configuration later, especially if you want the remote debugger to run as a service. For more information, see (Optional) Configure the remote debugger as a service.

Set up the remote debugger

You must have administrative permissions on the remote computer.

  1. Locate the Remote Debugger application. (Find msvsmon.exe in the location where it has been installed, or open the Start menu and search for Remote Debugger.)

    If you are running the remote debugger on a remote server, you can right-click the Remote Debugger app and choose Run as administrator. If you are not running it on a remote server, just start it normally.

  2. When you start the remote tools for the first time (or before you have configured it), the Remote Debugging Configuration dialog box appears.

    RemoteDebuggerConfWizardPage

  3. If the Windows Service API is not installed (which happens only on Windows Server 2008 R2), choose the Install button.

  4. Select the network types you want use the remote tools on. At least one network type must be selected. If the computers are connected through a domain, you must choose the first item. If the computers are connected through a workgroup or homegroup, you need to choose the second or third item as appropriate.

  5. Choose Configure remote debugging to configure the firewall and start the tool.

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

    RemoteDebuggerWindow

    The remote debugger is now waiting for a connection. Make a note of the server name and port number that is displayed, because this must match the configuration you later use in Visual Studio.

    When you are finished debugging and need to stop the remote debugger, click File > Exit on the window. You can restart it from the Start menu or from the command line:

    <Visual Studio installation directory>\Common7\IDE\Remote Debugger\<x86, x64, or Appx>\msvsmon.exe.

Start a remote debugging session

You start, stop, and navigate a remote debug session the same way you do a local session. On pre-Creator's Update versions of Windows 10, make sure the Remote Debugging Monitor is running on the remote device.

Then choose Start Debugging on the Debug menu (Keyboard: F5). The project is recompiled, then deployed to and started on the remote device. The debugger suspends execution at breakpoints, and you can step into, over, and out of your code. Choose Stop Debugging to end your debug session and close the remote app.

See Also

Advanced remote deployment options
Testing UWP apps with Visual Studio
Debug apps in Visual Studio