Run UWP apps on a remote machine

Applies to Windows only

To run a UWP app on a remote machine, you must attach to it using the Visual Studio Remote Tools. 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, see Debug an Installed App Package. Remote tools will be installed automatically.
  • For Windows 10 Xbox, IOT, and HoloLens devices, see Debug an Installed App Package. Remote tools will be installed automatically.
  • For Windows Phone, you must be physically connected to the phone, you must either install a developer's license (Windows Phone 8 and 8.1) or enable developer mode (Windows Mobile 10), and you must select Device as the debug target. Remote tools are not required or supported.

For Windows 8.1 PCs and 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 an Ethernet cable. Debugging over the internet is not supported.

  • The remote device must be enabled for development.

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

  • You must be an administrator on the remote device to configure the firewall during installation. You must have user access to the remote device to run or connect to the remote debugger.

Security

By default, the remote debugger uses Windows Authentication.

Warning

You can also choose to run the remote debugger 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 of from malicious or hostile traffic.

How to connect directly to a remote device

To connect directly to a remote device, connect the Visual Studio computer to the device with a standard Ethernet cable. If the device does not have an Ethernet port, you can use a USB to Ethernet adapter to connect to the cable.

Download and Install the Remote Tools

  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 Update 4 Remote tools Always download the version matching your device operating system (x86 or x64). For older browsers, use these direct links: Remote Tools (x64) and Remote Tools (x86).
    Visual Studio 2017 (older) Remote tools If prompted, join the free Visual Studio Dev Essentials group or you can sign in with a valid Visual Studio subscription. Then reopen the link if necessary.
    Visual Studio 2015 Update 3 Remote tools If prompted, join the free Visual Studio Dev Essentials group or you can sign in with a valid Visual Studio subscription. Then reopen the link if necessary.
    Visual Studio 2015 (older) Remote tools If prompted, join the free Visual Studio Dev Essentials group or you can sign in with a valid Visual Studio subscription. Then reopen the link if necessary.
    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.

Configuring 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 Select Remote Debugger 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.

Choosing the remote device for C# and Visual Basic projects

Managed project properties for remote debugging

  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.

Choosing the remote device for JavaScript and C++ projects

C++ project properties for remote debugging

  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.

Running a remote debugging session

You start, stop, and navigate a remote debug session the same way you do a local session. Before you start debugging, 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. For more information, see Debug apps in Visual Studio.

See Also

Testing UWP apps with Visual Studio
Debug apps in Visual Studio