# Help Topics:

1. Overview -- How do I remote debug from Visual Studio?
2. Command Line -- What are the remote debugger command-line options? What do they do?
3. Setup -- How do I setup remote debugging?
4. Security -- What security options are available when remote debugging?
5. User Interface -- What do user interface options do?
6. Firewall Configuration -- How does the remote debugger work through the firewall?
7. Windows Web Services -- Why does the remote debugger need Windows Web Services?
8. Running multiple instances of the remote debugger -- How do multiple users run the remote debugger on the same shared computer?
9. Service -- Should I run the remote debugger as a Service?

# Overview

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:

1. Run the remote debugger (msvsmon.exe) on the computer that you want to debug to. See the setup help for more information.
2. Configure Visual Studio to connect to the remote debugger
   - If you want to launch a C#/VB project: Open properties for your project (right click in solution explorer), and on the Debug tab, check the option to use a remote machine.
   - If you want to launch a C++ project: Open properties for your project (right click in solution explorer), and on the Debugger menu, change the Debugger to Launch value to Remote Windows Debugger. Set the Remote Command property to path that the remote computer should use.
   - To attach to an already running process: Start the Attach to Process dialog from the Tools or Debug menu, and enter the remote computer name into the Qualifier edit box.
   - To debug a web site: Open the web site from a remote file share, and then configure the Custom Web Server property to the web server's URL (exe: http://myserver).
   - To launch an executable without a project: Create a debugger project by opening the executable as a project (File->Open Project) and entering the path to the executable that you want to debug (ex: \\MyTestComputer\c$\MyTest.exe). Then open project properties and change the Connection property. Also adjust the Executable property to the path that the remote computer should use.
3. Start debugging

# Command Line

Description of all remote debugger command line options
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: /quiet : error dialogs (or other blocking UI) will be suppressed. The exit code for the msvsmon.exe process indicates any errors. /nofirewall : the firewall should not be configured Firewall profile options: /domain : enable domain networks, such as a workplace network /private : enable private networks, such as my home or work network /public : enable public networks, such as those in airports and coffee shops If no profile option is given, all profiles will be configured.
/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.

# Setup

There are several different ways to setup remote debugging.

### Running the remote debugger off a file share

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:

- Launching Windows Store apps. However, it is still possible to manually attach.
- JavaScript debugging
- Stepping into a web service. However, it is still possible to manually attach.
- Automatically launching an ASP.NET site under the debugger. Manually attaching is still possible.

### Running remote debugger setup on the remote computer

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.

# Security

The remote debugger supports two authentication modes:

1. Windows Authentication mode (used by default)
2. No Authentication mode

### Windows Authentication mode

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

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.

# User Interface

### Status window

The status window shows remote debugging events. Successful connections and successful initializations are shown.

### Options dialog

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.

### Permissions dialog

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.

# Firewall Configuration

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.

# Windows Web Services

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.

# Running multiple instances of the remote debugger

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

# Running the remote debugger as a service

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:

1. The user must be a member of the Administrators group to allow debugging of any process.
2. The user must be granted the 'Log on as a service' privilege. This can be done with the 'Local Security Policy' administrative tool.

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