Use common language runtime (CLR) debugging API, tool vendors can write debugger to debug applications running on the CLR environment. To debug CLR code can support any kind of code. CLR debugging API is mainly implemented using unmanaged code. Therefore, debugging API presented as a set of component object model (COM) interfaces. API consisting of:
-
A collection of COM objects and interfaces CLR implementation.
-
A collection of COM callback interface must be implemented by the debugger.
CLR debugging program
The following sections describe how to debug API handles typical of the common language runtime debugging programs. Note that certain aspects of the direct support runtime, and may be other programs to support interoperable with the current method.
Out of process debugging
In-process debugging, the debugger is not the debugging process, and in another process (i.e., external debug object). This scheme reduces the interaction between the debugger and debug target. Therefore, it can be more accurately describe the process.
CLR debugging API support foreign direct debugging process. API handles all communication between the debugger and debug managed objects managed code section to support debugging.
Although the CLR debugging API for-process, but some debugging logic (such as thread synchronization) within the same process but with the debug object. In most cases, this is supposed to keep the debugger transparent implementation details. For more information about thread synchronization, see the CLR Debugger Architecture. Debugging API drawback is that it can not be used in a process to check for crash dump outside.
In-process debugging
In the .NET Framework 1.0 and 1.1 versions, CLR debugging process debugging API supports limited, debugging within a restricted process, the profiler can be used to debug the API checking. It is replaced with a more consistent set of API functions and analysis in the .NET Framework 2.0, the in-process debugging. For more information about these changes, see the stack snapshot overview of the analysis and object checking in.
Remote debugging process
In the remote process debugging, the debugger user interface and the process being debugged not on the same computer. If the impact of the debugger and debuggee running on the same computer each other, this program can be useful. This effect may be caused by the following reasons:
-
Limited resources.
-
Location-dependent.
-
Bug affect the operating system.
CLR debugging API does not directly support remote debugging process. Based CLR debugging API debugger must still exists outside the object debugging process. Therefore, this solution requires a proxy process on the computer debugging object is located.
Unmanaged code debugging
Managed code and unmanaged code is usually coexist in the same process. This usually requires two types of code while debugging.
CLR debugging API support across the boundaries between managed code and unmanaged code execution single-step debugging, but does not directly support unmanaged code debugging. However, by sharing the Win32 debugging functions, the CLR debugging API can coexist with unmanaged code debugger.
In addition, CLR debugging API provides two options for debugging process:
-
"Additional soft" option, this option only to debug managed part of the process. Soft debugger attached to the process can then be separated from the process.
-
"Hard plus" option, this option in the debugging managed and unmanaged part of the process, and all public events through the debugger to debug Win32 API.
A mixed-language environment
In component software, the different components may be constructed in different languages. The debugger must know the language differences, to be able to display the data in the correct format, the expression is evaluated, and so with the correct syntax.
CLR debugging API does not provide any direct mixed-language environment support, because there is no source CLR language concepts. By mapping an existing source application debugger, you should be able to function mapping of a given language to implement the function used.
Distributed multiple processes and procedures
Component program may include collaboration components that can run on different processes, or even run on different computers across the network. The debugger should be able to trace the execution logic between between processes and computers to provide a logical view of what happened.
CLR debugging multi-process debugging API does not provide any direct support. API used directly debugger should provide such support, and existing methods for performing this operation should continue to be valid.
API category
Debug Interface API includes the following three groups, which typically consists of three CLR interfaces used by the debugger, and the form of the non-managed code are implemented:
-
Interface support for CLR application debugging.
-
Interface to allow access to the symbolic debugging information, the information is typically stored in a program database (the PDB) file.
-
Support Interface on a computer query process and application domain.
In addition debugging API relies on two sets of interfaces:
-
Static program for processing information (type information such as classes and methods) checking metadata API.
-
Symbol store API support for source-level debugging for managed code debugger.
Debug interface can also be divided into functional categories shown in the following table.
| API category |
Explanation |
|---|---|
| registered |
The debugger call interface to register with the CLR and request notification when certain events occur. |
| Notice |
CLR debugger for various events notification and return the callback interface information request. These interfaces must be implemented by the debugger. |
| Breakpoints |
The debugger breakpoint call to retrieve information about the interface. |
| carried out |
The debugger calls to control and access the debug object to perform the call stack interface. |
| information |
The debugger call to get information about debugging object interface. |
| Enumeration |
The debugger call to enumerate the object's interface. |
| modify |
The debugger call interface to modify the debugging code. |
The following sections describe features of the common language runtime (CLR) debugging services provided.
Attached to the program or start a program
CLR allows you to attach the debugger to a running program or to start the process. CLR debugging services allow you to attach the debugger to the program caused by abnormal untreated, it supports real-time (JIT) debugging. However, no debugging information provided may be running low in debug mode. Program can always make their own run in debug mode in order to avoid this problem. For more information on debug mode, see the following:
-
Debugging, tracking and analysis
-
Application Features
-
DebuggableAttribute
Control execution
CLR debugging services provide a variety of ways to control program execution. These include breakpoints, single-step execution, exception notification, function evaluation and launch other programs and closing of the event.
CLR debugging API is only available to managed code execution control. If you want to implement execution control in unmanaged code, you must implement this function alone in the debugger.
Breakpoints
By specifying code, and Microsoft intermediate language should be interrupted position (MSIL) or native offset, you can create a breakpoint. Then, when faced with a breakpoint, the debugger will be notified. Debugging API does not directly support conditional breakpoints. However, by evaluating the expression in response to a break and decide whether or not to notify the user of information about stopping the debugger can achieve these breakpoints.
Single-step execution
CLR debugging services provide a variety of single-step execution function. Embodiment the program may take an instruction one embodiment step through the code (a single step execution), a series of instructions that may be used to step through the code (step execution range). It may be skipped, performed step into or out of a function. If a single-step interrupt operation exception occurs, CLR debugging services may also notify the debugger.
Although the service does not directly support debugging step through the unmanaged code, however, when a single-step operation to reach the unmanaged code debugging service will provide callbacks to control to the debugger. Commissioning services are also provided to allow the debugger to determine when unmanaged code from managed code into the function.
CLR does not directly provide source level stepping. The debugger can range by stepping with its own source mapping information to provide this functionality in combination. You can use the symbol store interface to obtain the source level information. For more information about these interfaces, see Diagnostic Symbol Store (Unmanaged API Reference).
abnormal
When using the CLR debugging services, the emergence of the first and second abnormal when abnormal managed code, the debugger will be notified. Every object can be used to check triggered.
CLR unmanaged code will not process the native abnormal, unless these abnormalities propagated up to managed code. However, you can still use shared with CLR debugging services Win32 debugging services to handle unmanaged exceptions.
Event
When an event occurs in multiple programs, CLR debugging services will notify the debugger. These events include process creation and exit, thread creation and exit, and exit the application domain creation, assembly loading and unloading, loading and unloading modules as well as class loading and unloading. In order to ensure good performance, you can load and unload event for the module is disabled class. By default, the class load and unload event is disabled.
Thread Control
CLR debugging services provide an interface for suspend and resume execution of individual (hosting) thread.
Check program status
When the process is stopped, CLR debugging services detailed examination of each part of the process of running managed code. You can check the process to obtain a list of physical threads.
You can check the thread to detect the call stack. You can break the thread call stack at two levels: level stack frame and chain level. The call stack is first broken down into chains. Chain is a contiguous logical call stack segment. It contains the managed or unmanaged stack frame, but can not contain both. In addition, all managed to call a single chain frames share the same CLR context. Chain may be hosted chain, the chain may be unmanaged.
Each chain can be managed separately divided into a single stack frame. Each stack frame represents a method call. You can query the stack frame to get the code it is performing, or get its parameters, local variables, and the machine registers.
Unmanaged chain does not contain a stack frame. Instead, it provides the address range assigned to the stack unmanaged code. Unmanaged code debugger is responsible for the unmanaged part of the stack is decoded, and provide a stack trace.
Remark
CLR debugging service concept of local variables appear in the source code is not supported. The debugger is responsible for mapping local variables to their assignment.
CLR debugging service also provides access to global variables, static variables and class thread-local variables.
Modify the program state
CLR debugging service allows the debugger to change the physical location of the instruction pointer during execution, although this may be a dangerous operation. If the following conditions are met, you can successfully change the instruction pointer:
-
The current instruction pointer and instruction pointer are located at a certain point sequence. The statement is roughly the sequence point boundary.
-
Is not in the target instruction pointer exception filter, catch finally block or blocks.
-
Current instruction pointer is located in the catch block, the target instruction pointer is not outside the catch block.
-
In the target instruction pointer the current instruction pointer to the same frame.
When the instruction pointer of a physical location changes, the variable of the current instruction pointer position is mapped to the variable at the target instruction pointer position. At the target instruction pointer reference position initialized properly garbage collection.
After the instruction pointer changes, CLR debugging services will stack any cached information is marked as invalid, and refresh the information in the next time you need. Cacheable point stack information (e.g., frames and chains) pointer debugger this information should be refreshed after changing the instruction pointer.
The debugger can also modify the data of the program when the program is stopped. The debugger can be employed in a similar manner to check for changes in the function is a function of local variables and parameters. The debugger can also update the fields of arrays and objects, as well as static fields and global variables.
Use the "Edit and Continue"
During a debugging session, you can use the "Edit and Continue" feature do the following:
-
Edit the source code.
-
Recompile the source code modification.
-
The remaining state to retain the run-time debugging executable file.
-
Continue to run a debugging session, without having to start from scratch to re-run the executable file.
A function evaluated
To evaluate the value of the expression and dynamic properties of the user object, the debugger requires code to run debugging process. CLR Debugger allows the debugger to a function or method call, and running in a debug object process.
CLR allows the debugger to stop such operations, since this operation can be dangerous (e.g., existing code which may cause a deadlock). If successfully stopped the evaluation, it will be treated as if the thread has never been evaluated as just part of the evaluation of local variables will have some side effects. If the function call in the unmanaged code blocks or in some way, the end may not be evaluated.
After the function evaluation is completed, CLR will use callbacks to notify the debugger evaluation was done correctly or whether the function threw an exception. ICorDebugValue and methods may be used to check the results ICorDebugValue2 evaluated.
To evaluate the function thread in which security must be carried out at the security point of stop garbage collection in managed code. (Untreated abnormality allow evaluation function.) In the unoptimized code, the security is very common; most breakpoints or single-step operation MSIL stage will be completed in a safe point. However, these points are optimized code can be very rare. Sometimes the entire function may not be any safe point. Safety security dot frequency can be due to garbage collection function initiated. Even in the unoptimized code, or it may not be stopped at the position 1. Optimizing or optimizing code, ICorDebugController :: Stop method is rarely located at a safe point.
CLR debugging services will set up a new chain on a thread, in order to start function evaluation function value and call request. Once evaluated, you can see various aspects of the debugging API: implementation of control, inspection, function evaluation and so on. Supports nested evaluation and processing breakpoints in the normal manner.
Dynamic code injection
Some debugger allows the user to enter and execute arbitrary statements ** "instant" ** window. CLR debugging services support this scenario. Within a reasonable range, you can dynamically inject code without any restrictions. (For example, does not allow non-local goto statement.)
Dynamic code injection by the "Edit and continue" operation is used in conjunction evaluation function implemented. To inject code in a function package, and by using the "Edit and Continue" inject. Then, the injection function will be evaluated. If necessary, you can provide ByRef parameters to the function package, the side effects of direct and permanent effect.
Supported Environments
CLR supports all processors and operating systems are available on the CLR debugging features, with the following exceptions:
-
Does not support the "Edit and Continue" and mixed-mode debugging 64-bit operating system. SetIP Method (ICorDebugILFrame :: SetIP and ICorDebugNativeFrame :: SetIP) have additional restrictions on the 64-bit operating system. The remaining functions are the same on all processors (but in the presence of a particular representation of the data processor, for example, the size of a pointer, register contexts, etc.).
-
Based on does not support the "Edit and Continue" and mixed-mode debugging on Win9x operating system. The rest of the function should be the same on all operating systems. However, there are still some specific exceptions to document individual features described.