Remote debugging allows you to debug programs which run on a different computer than the computer where Visual Studio is running.
With this release of Visual Studio, remote debugging has never been easier. Basic steps:
| Option | Description |
|---|---|
| /allow user_name | Allows specified users to connect to the remote debugger. Only fully trusted users should be allowed to debug. If a malicious user was given permission to connect, they would be able to take over the user account of the user running the remote debugger. User names should be semicolon or comma separated (example: SomeDomain\Bob;SomeDomain\Alice) |
| /port port_number | Changes the TCP/IP port number that the remote debugger will listen on. This option is commonly used to allow multiple instances of the remote debugger to run on the same computer. |
|
/wow64port port_number
(Windows x64 only) |
On Windows x64, the remote debugger listens on an additional port to allow debugging 32-bit processes
running under the WOW64 (Windows 32-bit On Windows 64-bit) emulation layer. The /wow64port option
allows this port number to be configured. This may be useful to accommodate a hardware firewall.
If unspecified, the debugger will attempt to use 4025, but will fall back to any unused port if 4025
is already in use.
Note that it is not recommended to ask Visual Studio to directly connect to this port, as this will only allow for debugging 32-bit process. Instead, if Visual Studio connects to the primary port (see /port), it will automatically switch to the 32-bit port when needed. |
| /timeout number_of_seconds | Configures the number of seconds the remote debugger waits before exiting if no user is connected. In Windows Authentication mode, the default timeout is infinite. In No Authentication mode, the default timeout is 15 minutes. |
| /noauth | Switches the remote debugger from Windows Authentication mode to No Authentication mode. For more information, see Security. |
| /anyuser | In No Authentication mode, Visual Studio sends the current user's username to the remote debugger. The remote debugger uses this username for a safety check to help prevent users from accidentally connecting to a different user's remote debugger. This option disables the safety check so that any user can connect. |
| /nostatus | Starts the remote debugger with the status window hidden. The status window can be shown from the remote debugger's system tray icon. |
| /nodiscovery | Starts the remote debugger with discovery disabled. This remote debugger instance will not be found in Visual Studio's Find Remote Debugger Instance dialog. |
| /silent | Tells the remote debugger not to show the user interface. |
| /prepcomputer [options] |
Prepares this computer for remote debugging by ensuring the
Windows Firewall is configured. To use /prepcomputer, msvsmon should
be launched as an administrator.
Several additional switches may be passed along with /prepcomputer.
General options:
Firewall profile options: |
| /ntlm |
By default, the remote debugger negotiates the strongest Windows authentication
provider that can be used between the Visual Studio computer and the remote debugger's
computer. Today, this will generally be Kerberos authentication if both computers
are on the same domain. This is done to provide the best possible security.
The '/ntlm' option instructions the remote debugger to instead use NTLM authentication provider. This option is generally not recommended. However, it can be very useful in situations where Kerberos is failing to authenticate. |
| /hostname hostname_value | Instructs the remote debugger to listen on the network using the specified hostname value, or IP address value. On a computer with multiple network cards, or with multiple assigned DNS host names, this option can be used to restrict which of these will allow remote debugging. For example, a server may have an internet facing address, and an internal address. By using '/hostname private_ip_address', remote debugging will not be available through the internet facing address. |
| /noclrwarn | The remote debugger tries to load the 2.0 Common Language Runtime (CLR). This option suppresses the warning that appears if the installed CLR is incompatible. This option is useful if you don't want to debug managed code. |
| /nosecuritywarn | When using the '/noauth' or '/allow' command line options, the remote debugger normally displays a warning because both of these options are dangerous unless used with care. The '/nosecuritywarn' disables these warnings. This option should only be used if you understand the security implications of the '/noauth' and '/allow' options. |
| /nofirewallwarn | Do not warn if the Windows Firewall blocks remote debugging. |
| /nowowwarn | 64-bit versions of Windows are capable of running 32-bit applications. This technology is called 'WOW'. When running the remote debugger under WOW, it is not able to attach to 64-bit processes. This option turns off checking for this condition. |
| /FallbackLoadRemoteManagedPdbs | Enables loading managed PDB files on this computer (the target computer) when the PDB file cannot be found on the Visual Studio computer. When enabled, the debugger will search in the path where the PDB was originally built and also next to where the dll/exe is currently located. This option may have a performance impact on remote debugging since now any queries for the PDB will go over the network, but it is minimal in typical cases. |
| /name server_name | (deprecated) Causes the remote debugger to listen at specified server name in addition to a TCP/IP port. Visual Studio can connect using this server name using the <server_name>@<computer_name> syntax. When using this option, the remote computer must allow file sharing access. This option is not recommended and is provided only for backward compatibility. |
There are several different ways to setup remote debugging.
For many scenarios, the easiest way to setup remote debugging is to run the remote debugger (msvsmon.exe) from a file share. Visual Studio installs msvsmon.exe into these directories:
Program Files\Microsoft Visual Studio 17.0\Common7\IDE\Remote Debugger\x86
Program Files\Microsoft Visual Studio 17.0\Common7\IDE\Remote Debugger\x64
Program Files\Microsoft Visual Studio 17.0\Common7\IDE\Remote Debugger\arm
By sharing out the 'Remote Debugger' directory on the Visual Studio computer, you can run msvsmon.exe on the remote computer.
Features that will not work if msvsmon.exe is run from a share:
The remote debugger is included in the 'Remote Tools for Visual Studio 2022' installer. The latest version can be downloaded from the Microsoft download center by visiting microsoft.com, and searching for the product.
The remote debugger supports two authentication modes:
Windows Authentication mode uses Windows's built-in security to provide a high level of security. Kerberos and/or NTLM authenticate and encrypt all requests. The remote debugger will, by default, only accept connections from the user who launched the remote debugger and members of the Administrators group. Additional users must be explicitly granted permissions using Tools->Permissions from within the remote debugger's UI, or from the command line using the /allow option.
No Authentication mode has no security. Visual Studio sends the current username to the remote debugger, but this information is not verified. No Authentication mode should never be used on a network that may have hostile traffic. When using no authentication mode, it is recommended to use firewall settings to restrict which computers are able to connect to the remote debugger. Even with strong firewall settings, no authentication mode offers significantly weaker protection than Windows Authentication mode. So it is recommended to use Windows Authentication mode whenever possible.
The status window shows remote debugging events. Successful connections and successful initializations are shown.
| Option | Description |
|---|---|
| Windows Authentication | This option enables Windows Authentication mode. For more information, see Security. |
| Permissions | In Windows Authentication mode, this option opens the permissions dialog. |
| No Authentication | This option enables No Authentication mode. For more information, see Security. |
| TCP/IP port number | In No Authentication mode, the remote debugger will listen on a TCP/IP port. This option can be used to configure what TCP/IP port to listen on. |
| Allow any user to debug | In No Authentication mode, Visual Studio sends the current user's username to the remote debugger. The remote debugger uses this username for a safety check to help prevent users from accidentally connecting to a different user's remote debugger. This option disables the safety check so that any user can connect. |
| Maximum idle time (seconds) | Configures the number of seconds the remote debugger waits before exiting if no user is connected. In Windows Authentication mode, the default timeout is infinite. In No Authentication mode, the default timeout is 15 minutes. |
In Windows Authentication mode, this dialog can be used to specify which users can connect and debug through the remote debugger. Only fully trusted users should be allowed to debug. If a malicious user was given permission to connect, they would be able to take over the user account of the user running the remote debugger.
To allow remote debugging, any firewalls between the Visual Studio computer and the remote debugger must be configured so that the remote debugger (msvsmon.exe) will be able to receive data sent from Visual Studio. The remote debugger is able to automatically configure the Windows Firewall.
When using a firewall other than the Windows Firewall such as third party software firewall or a hardware firewall, the firewall must be manually configured to allow remote debugging. To do so, allow traffic on TCP/IP ports that msvsmon.exe is listening on. By default, these are port 4026 and 4025, where 4026 is used on all operating systems, and 4025 is used only on Windows x64 to allow debugging x86 processes.
By default, the Remote Debugger Configuration dialog configures the Windows Firewall rule to apply to all network profiles (Domain, Private and Informal/Public). The Informal/Public configuration enables the scenario when the Visual Studio computer is directly connected to a target device via an Ethernet cable. The Visual Studio remote debugger uses authentication and encryption to maintain security in this scenario.
You can disable one or more network profiles by clearing the appropriate checkboxes (Domain/Private/Informal). However, if all currently active profiles are unchecked, the configuration dialog disables the 'Configure remote debugging' button. For example, if your computer is connected to a single network, and this network is an Informal network, then unchecking the Informal checkbox will disable the Configure button.
Remote debugging is implemented using the Windows Web Services API. The Windows Web Services API is a building block that applications, such as the remote debugger, can use to communicate over the network. This API is already included in Windows 7, Windows Server 2008 R2 and later operating systems. For Windows Server 2008 (pre-R2), the Visual Studio Remote Tools setup will automatically install the API.
Multiple instances of the remote debugger may be run on the same computer. This is required if there is a single server shared by multiple users, and each user wants to run their own instance of the remote debugger to debug their own processes.
Each instance of the remote debugger must run on its own TCP/IP port number. The remote debugger can be configured to listen at a specific port number from Tools->Options in the remote debugger, or from the command line using /port:<value>.
To connect to a specific instance of the remote debugger, include the port number along with the computer name in the 'remote machine'/'qualifier' setting (ex: MyServer:1234 to connect to port 1234 on MyServer).
You can run the remote debugger as either a Windows service or a Windows application. Running the remote debugger as a service allows you to easily debug server applications such as ASP.NET without logging onto the remote computer.
Running the remote debugger as a service causes it to always run and listen on the network. It is not recommended to run the remote debugger as a service for debugging client applications.
With the Visual Studio 2022 Remote Debug Configuration wizard, you can control the username and password that the remote debugger service runs under. When the remote debugger is running as a service, the following requirements must be met to debug remotely:
The default user for the remote debugger service is 'LocalSystem.'
The name of the service is 'Visual Studio 2022 Remote Debugger'. It is recommended that you only control the service through the Visual Studio 2022 Remote Debugger Configuration wizard. If necessary, it can be controlled through the computer management administration tool, or on the command line -- 'net stop msvsmon170' or 'net start msvsmon170'.