Attach to Running Processes with the Visual Studio Debugger
This topic shows you how to attach to a running process, attach to a process on a remote computer, and troubleshoot attach errors.
Why debug attached processes?
The Visual Studio debugger has the ability to attach to a process that is running outside of Visual Studio. You can use this attach capability to do the following:
Debug an application that was not created in Visual Studio.
Debug multiple processes simultaneously. You can also debug multiple processes by starting multiple projects within a single solution.
Debug a process running on a remote computer.
Debug a DLL that runs in a separate process that cannot easily be started from Visual Studio, for example, a service or an ISAPI DLL running with Internet Information Services.
Start the debugger automatically when a process crashes while running outside of Visual Studio. This is Just-In-Time debugging.
After you have attached to a program, you can use debugger execution commands, inspect the program state, and so on. For more information, see Debug One or More Processes in Visual Studio, Start, Break, Step, Run through Code, and Stop Debugging in Visual Studio and Viewing Data in the Debugger. Your ability to inspect the program may be limited, depending on whether the program was built with debug information and whether you have access to the program's source code, and whether the common language runtime JIT compiler is tracking debug information.
.gif "C++ note") C++ Note |
|---|
For the debugger to attach to code written in C++, the code needs to emit DebuggableAttribute. You can add this to your code automatically by linking with the /ASSEMBLYDEBUG linker option. |
Warning
To attach to a Windows Store app that is written in JavaScript, you must first enable debugging for the app. See Attach the debugger in the Windows Dev Center.
Attach to a running process
On the Debug menu, select Attach to Process.
In the Attach to Process dialog box, find the program that you want to attach to from the Available Processes list.
If the program that you want to debug is running on another computer, use the Qualifier list box to select or specify the remote computer. For more information, see Remote Debugging and Diagnostics.
If the process is running under a different user account, select the Show processes from all users check box.
If you are connected through Remote Desktop Connection, select the Show processes in all sessions check box.
In the Attach to box, make sure that the type of code you will debug is listed. The default Automatic setting tries to determine what type of code you want to debug. If the automatic setting is not appropriate:
Click Select.
In the Select Code Type dialog box, click Debug these code types and select the types to debug.
Click OK.
Click Attach.
The Available Processes list is displayed automatically when you open the Processes dialog box. Processes can start and stop in the background while the dialog box is open. However, the contents are not always current. You can refresh the list at any time to see the current list of processes by clicking Refresh.
You can be attached to multiple programs when you are debugging, but only one program is active in the debugger at any time. You can set the active program in the Debug Location toolbar or the Processes window.
Note
For the debugger to attach to managed code written in C++/CLI, the code must emit DebuggableAttribute. You can add this to your code automatically by linking with the /ASSEMBLYDEBUG linker option.
If you try to attach to a process owned by an untrusted user account, a security warning dialog box confirmation will appear. For more information see Security Warning: Attaching to a process owned by an untrusted user can be dangerous. If the following information looks suspicious or you are unsure, do not attach to this process.
In some cases, when you debug in a Remote Desktop (Terminal Services) session, the Available Processes list will not display all available processes. On Windows Server 2003 or later versions, if you are running Visual Studio as a user who has a limited user account, the Available Processes list will not show processes that are running in Session 0, which is used for services and other server processes, including w3wp.exe. You can solve the problem by running Visual Studio under an administrator account or by running Visual Studio from the server console instead of a Terminal Services session. If neither of those workarounds is possible, a third option is to attach to the process by running vsjitdebugger.exe -p ProcessId from the Windows command line. You can determine the process id using tlist.exe. To obtain tlist.exe, download and install Debugging Tools for Windows, available at https://go.microsoft.com/fwlink/?LinkId=168279.
To stop debugging the attached process, click Debug / Stop Debugging, or stop running the attached process.
Attach to a process on a remote computer
When you use the Attach to Process dialog box, you can select another computer that has been set up for remote debugging. For more information, see Set Up the Remote Tools on the Device. When you have selected a remote computer, you can view a list of available processes running on that computer and attach to one or more of the processes for debugging.
To select a remote computer:
In the Attach to Process dialog box, select the appropriate connection type from the Transport list. Default is the correct setting for most cases.
Use the Qualifier list box to choose the remote computer name by one of the following methods:
Type the name in the Qualifier list box.
Click the drop-down arrow attached to the Qualifier list box and select the computer name from the drop-down list.
Click the Find button next to the Qualifier list to open the Select Remote Debugger Connection dialog box. The Select Remote Debugger Connection dialog box lists all the devices that are on your local sub-net, and any device that is directly attached to your computer through an Ethernet cable. Click the computer or device that you want, and then click Select.
The Transport setting persists between debugging sessions. The Qualifier setting persists between debugging sessions only if a successful debugging connection occurs with that qualifier.
Troubleshoot attach errors
When the debugger attaches to a running process, the process can contain one or more types of code. The code types the debugger can attach to are displayed and selected in the Select Code Type dialog box.
Note
For the debugger to attach to managed code written in C++, the code must emit DebuggableAttribute. You can add this to your code automatically by linking with the /ASSEMBLYDEBUG linker option.
Warning
To attach to a Windows Store app that is written in JavaScript, you must first enable debugging for the app. See Attach the debugger in the Windows Dev Center.
Sometimes, the debugger can successfully attach to one code type, but not to another code type. This might occur if you are trying to attach to a process that is running on a remote computer. The remote computer might have remote debugging components installed for some code types but not for others. It can also occur if you try to attach to two or more processes for direct database debugging. SQL debugging supports attaching to a single process only.
If the debugger is able to attach to some, but not all, code types, you will see a message identifying which types failed to attach.
If the debugger successfully attaches to at least one code type, you can proceed to debug the process. You will be able to debug only the code types that were successfully attached. The preceding example message shows that the script code type failed to attach. Therefore, you would not be able to debug script code within the process. The script code in the process would still run, but you would not be able to set breakpoints, view data, or perform other debugging operations in the Script.
If you want more specific information about why the debugger failed to attach to a code type, you can try to reattach to only that code type.
To obtain specific information about why a code type failed to attach
Detach from the process. On the Debug menu, click Detach All.
Reattach to the process, selecting only a single code type.
In the Attach to Process dialog box, select the process in the Available Processes list.
Click Select.
In the Select Code Type dialog box, select Debug these code types and the code type that failed to attach. Clear any other code.
Click OK. The Select Code Type dialog box closes.
In the Attach to Process dialog box, click Attach.
This time, the attach will fail completely, and you will get a specific error message.
See Also
Concepts
Debug One or More Processes in Visual Studio
Just-In-Time Debugging in Visual Studio