From 4cc4efea95a0d049e0ac42cdd53dd457ffafad7f Mon Sep 17 00:00:00 2001 From: Mike McLaughlin Date: Tue, 3 Dec 2024 14:47:03 -0800 Subject: [PATCH] Add .NET Debugger Extensions documentation (#43825) * Add .NET Debugger Extensions documentation Add Native AOT supported commands Improve doc score. lldb -> LLDB. * Fix lint run * Update docs/core/diagnostics/tools-overview.md Co-authored-by: Tom McDonald * Review feedback - add new files to toc.yml * Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --------- Co-authored-by: Tom McDonald Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/diagnostics/debugger-extensions.md | 242 ++++++++++++++++++ .../diagnostics/dotnet-debugger-extensions.md | 80 ++++++ docs/core/diagnostics/dotnet-sos.md | 18 +- .../diagnostics/sos-debugging-extension.md | 28 +- docs/core/diagnostics/tools-overview.md | 4 +- docs/navigate/tools-diagnostics/toc.yml | 4 + 6 files changed, 351 insertions(+), 25 deletions(-) create mode 100644 docs/core/diagnostics/debugger-extensions.md create mode 100644 docs/core/diagnostics/dotnet-debugger-extensions.md diff --git a/docs/core/diagnostics/debugger-extensions.md b/docs/core/diagnostics/debugger-extensions.md new file mode 100644 index 0000000000000..5c05635a2c3ae --- /dev/null +++ b/docs/core/diagnostics/debugger-extensions.md @@ -0,0 +1,242 @@ +--- +title: .NET debugger extensions +description: Learn about the debugger extensions for .NET, which provide information about the internal CLR environment. +ms.date: 09/11/2023 +ms.topic: reference +helpviewer_keywords: + - ".NET debugger extensions" + - "debugger extensions" + - "SOS.dll" +--- + +# .NET debugger extensions + +The .NET debugger extensions let you view information about code that's running inside the .NET runtime, both on live processes and dumps. The extensions are preinstalled with [Windbg](/windows-hardware/drivers/debugger/debugger-download-tools), and can be [downloaded](dotnet-debugger-extensions.md) for use with LLDB. You can use the .NET debugger extensions to: + +- Collect information about the managed heap. +- Look for heap corruptions. +- Display internal data types used by the runtime. +- View information about all managed code running inside the runtime. + +The .NET debugger extensions include commands from the existing [dotnet-sos](dotnet-sos.md) tool as well as new commands. A limited set of commands are also now supported for the Native AOT runtime. + +## Syntax + +Under windbg: `![command] [options]` + +Under LLDB: `sos [command] [options]` + +Many of the commands have aliases or shortcuts under LLDB: `clrstack [options]` + +## Commands + +The following table of commands is also available under **Help** or **soshelp**. Individual command help is available using `soshelp `. + +| Command | Description | +|---------|-------------| +| **bpmd** [**-nofuturemodule**] [\<*module name*> \<*method name*>] [**-md** <`MethodDesc`>] **-list** **-clear** \<*pending breakpoint number*> **-clearall** | Creates a breakpoint at the specified method in the specified module.

If the specified module and method has not been loaded, this command waits for a notification that the module was loaded and just-in-time (JIT) compiled before creating a breakpoint.

You can manage the list of pending breakpoints by using the **-list**, **-clear**, and **-clearall** options:

The **-list** option generates a list of all the pending breakpoints. If a pending breakpoint has a nonzero module ID, that breakpoint is specific to a function in that particular loaded module. If the pending breakpoint has a zero module ID, that breakpoint applies to modules that has not yet been loaded.

Use the **-clear** or **-clearall** option to remove pending breakpoints from the list. | +| **CLRStack** [**-a**] [**-l**] [**-p**] [**-n**] [**-f**] [**-r**] [**-all**] | Provides a stack trace of managed code only.

The **-p** option shows arguments to the managed function.

The **-l** option shows information on local variables in a frame. The .NET debugger extensions cannot retrieve local names, so the output for local names is in the format \<*local address*> **=** \<*value*>.

The **-a** option is a shortcut for **-l** and **-p** combined.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS looks up the symbols for every managed frame and if successful, displays the corresponding source file name and line number. The **-n** (No line numbers) parameter can be specified to disable this behavior.

The **-f** option (full mode) displays the native frames intermixing them with the managed frames and the assembly name and function offset for the managed frames. This option does not display native frames when used with `dotnet-dump`.

The **-r** option dumps the registers for each stack frame.

The **-all** option dumps the stacks of all the managed threads. | +| **COMState** | Lists the COM apartment model for each thread and a `Context` pointer, if available. This command is only supported on Windows. | +| **DumpArray** [**-start** \<*startIndex*>] [**-length** \<*length*>] [**-details**] [**-nofields**] \<*array object address*>

-or-

**DA** [**-start** \<*startIndex*>] [**-length** \<*length*>] [**-details**] [**-nofields**] *array object address*> | Examines elements of an array object.

The **-start** option specifies the starting index at which to display elements.

The **-length** option specifies how many elements to show.

The **-details** option displays details of the element using the **DumpObj** and **DumpVC** formats.

The **-nofields** option prevents arrays from displaying. This option is available only when the **-details** option is specified. | +| **DumpAsync** (**dumpasync**) [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [**-waiting**] [**-roots**] | DumpAsync traverses the garbage-collected heap and looks for objects representing async state machines as created when an async method's state is transferred to the heap. This command recognizes async state machines defined as `async void`, `async Task`, `async Task`, `async ValueTask`, and `async ValueTask`.

The output includes a block of details for each async state machine object found. These details include:
- A line for the type of the async state machine object, including its MethodTable address, its object address, its size, and its type name.
- A line for the state machine type name as contained in the object.
- A listing of each field on the state machine.
- A line for a continuation from this state machine object, if one or more has been registered.
- Discovered GC roots for this async state machine object.

Supported for Native AOT applications. | +| **DumpAssembly** \<*assembly address*> | Displays information about an assembly.

The **DumpAssembly** command lists multiple modules, if they exist.

You can get an assembly address by using the **DumpDomain** command. | +| **DumpClass** \<*EEClass address*> | Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address. | +| **DumpDomain** [\<*domain address*>] | Enumerates each object that's loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process. Since .NET (Core) only has one , **DumpDomain** only returns one object. | +| **DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]] | Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This command lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes.

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes.

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address.

Supported for Native AOT applications. | +| **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the common intermediate language (CIL) that's associated with a managed method.

Dynamic CIL is emitted differently than CIL that's loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens. | +| **DumpLock** [**--allthreads**] [**--waits**] | Displays information about System.Threading.Lock objects, such as those being held by threads (default), or those being waited upon by threads. | +| **DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filename*>] | Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log.

Supported for Native AOT applications. | +| **DumpMD** \<*MethodDesc address*> | Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function. | +| **DumpMT** [**-MD**] \<*MethodTable address*> | Displays information about a method table at the specified address. Specifying the **-MD** option displays a list of all methods defined with the object.

Each managed object contains a method table pointer. | +| **DumpModule** [**-mt**] \<*Module address*> | Displays information about a module at the specified address. The **-mt** option displays the types defined in a module and the types referenced by the module

You can use the **DumpDomain** or **DumpAssembly** command to retrieve a module's address. | +| **DumpObj** [**-nofields**] \<*object address*>

-or-

**DO** \<*object address*> | Displays information about an object at the specified address. The **DumpObj** command displays the fields, the `EEClass` structure information, the method table, and the size of the object.

You can use the **DumpStackObjects** command to retrieve an object's address.

You can run the **DumpObj** command on fields of type `CLASS` because they are also objects.

The `-`**nofields** option prevents fields of the object being displayed, it is useful for objects like String. | +| **DumpRuntimeTypes** | Displays the runtime type objects in the garbage collector heap and lists their associated type names and method tables. | +| **DumpStack** [**-EE**] [**-n**] [`top` *stack* [`bottom` *stack*]] | Displays a stack trace.

The **-EE** option causes the **DumpStack** command to display only managed functions. Use the `top` and `bottom` parameters to limit the stack frames displayed on x86 platforms.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS will look up the symbols for every managed frame and if successful displays the corresponding source file name and line number. The **-n** (No line numbers) parameter can be specified to disable this behavior. | +| **DumpSig** \<*sigaddr*> \<*moduleaddr*> | Displays information about a `Sig` structure at the specified address. | +| **DumpSigElem** \<*sigaddr*> \<*moduleaddr*> | Displays a single element of a signature object. In most cases, you should use **DumpSig** to look at individual signature objects. However, if a signature has been corrupted in some way, you can use **DumpSigElem** to read the valid portions of it. | +| **DumpStackObjects** [**-verify**] [`top` *stack* [`bottom` *stack*]]

-or-

**DSO** [**-verify**] [`top` *stack* [`bottom` *stack*]] | Displays all managed objects found within the bounds of the current stack.

The **-verify** option validates each nonstatic `CLASS` field of an object field.

Use the **DumpStackObject** command with stack tracing commands such as **K** (windbg) or **bt** (lldb) along with the **clrstack** command to determine the values of local variables and parameters. | +| **DumpVC** \<*MethodTable address*> \<*Address*> | Displays information about the fields of a value class at the specified address.

The **MethodTable** parameter allows the **DumpVC** command to correctly interpret fields. Value classes do not have a method table as their first field. | +| **EEHeap** [**-gc**] [**-loader**] | Displays information about process memory consumed by internal runtime data structures.

The **-gc** and **-loader** options limit the output of this command to garbage collector or loader data structures.

The information for the garbage collector lists the ranges of each segment in the managed heap. If the pointer falls within a segment range given by **-gc**, the pointer is an object pointer. | +| **EEStack** [**-short**] [**-EE**] | Runs the **DumpStack** command on all threads in the process.

The **-EE** option is passed directly to the **DumpStack** command. The **-short** parameter limits the output to the following kinds of threads:

Threads that have taken a lock.

Threads that have been stalled in order to allow a garbage collection.

Threads that are currently in managed code. | +| **EHInfo** [\<*MethodDesc address*>] [\<*Code address*>] | Displays the exception handling blocks in a specified method. This command displays the code addresses and offsets for the clause block (the `try` block) and the handler block (the `catch` block). | +| **FAQ** | Displays frequently asked questions. Not supported in `dotnet-dump`. | +| **FinalizeQueue** [**-detail**] | [**-allReady**] [**-short**] | Displays all objects registered for finalization.

The **-detail** option displays extra information about any `SyncBlocks` that need to be cleaned up, and any `RuntimeCallableWrappers` (RCWs) that await cleanup. Both of these data structures are cached and cleaned up by the finalizer thread when it runs.

The `-allReady` option displays all objects that are ready for finalization, regardless of whether they are already marked by the garbage collection as such, or will be marked by the next garbage collection. The objects that are in the "ready for finalization" list are finalizable objects that are no longer rooted. This option can be expensive, because it verifies whether all the objects in the finalizable queues are still rooted.

The `-short` option limits the output to the address of each object. If it is used in with **-allReady**, it enumerates all objects that have a finalizer that are no longer rooted. If it is used independently, it lists all objects in the finalizable and "ready for finalization" queues. | +| **FindAppDomain** \<*Object address*> | Determines the application domain of an object at the specified address. | +| **FindRoots** **-gen** \<*N*> | **-gen any** |\<*object address*> | Causes the debugger to break in the debuggee on the next collection of the specified generation. The effect is reset as soon as the break occurs. To break on the next collection, you have to reissue the command. The *\* form of this command is used after the break caused by the **-gen** or **-gen any** has occurred. At that time, the debuggee is in the right state for **FindRoots** to identify roots for objects from the current condemned generations. Only supported on Windows. | +| **GCHandles** [**-perdomain**] | Displays statistics about garbage collector handles in the process.

The **-perdomain** option arranges the statistics by application domain.

Use the **GCHandles** command to find memory leaks caused by garbage collector handle leaks. For example, a memory leak occurs when code retains a large array because a strong garbage collector handle still points to it, and the handle is discarded without freeing it.

Only supported on Windows. | +| **GCHandleLeaks** | Searches memory for any references to strong and pinned garbage collector handles in the process and displays the results. If a handle is found, the **GCHandleLeaks** command displays the address of the reference. If a handle is not found in memory, this command displays a notification. Only supported on Windows. | +| **GCInfo** \<*MethodDesc address*>\<*Code address*> | Displays data that indicates when registers or stack locations contain managed objects. If a garbage collection occurs, the collector must know the locations of references to objects so it can update them with new object pointer values. | +| **GCRoot** [**-nostacks**] [**-all**] \<*Object address*> | Displays information about references (or roots) to an object at the specified address.

The **GCRoot** command examines the entire managed heap and the handle table for handles within other objects and handles on the stack. Each stack is then searched for pointers to objects, and the finalizer queue is also searched.

This command does not determine whether a stack root is valid or is discarded. Use the **clrstack** and **U** commands to disassemble the frame that the local or argument value belongs to in order to determine if the stack root is still in use.

The **-nostacks** option restricts the search to garbage collector handles and reachable objects.

The **-all** option forces all roots to be displayed instead of just the unique roots. | +| **GCWhere** *\* | Displays the location and size in the garbage collection heap of the argument passed in. When the argument lies in the managed heap but is not a valid object address, the size is displayed as 0 (zero). | +| **Help** (**soshelp**) [\<*command*>] [`faq`] | Displays all available commands when no parameter is specified, or displays detailed help information about the specified command.

The `faq` parameter displays answers to frequently asked questions. | +| **HeapStat** [**-inclUnrooted** | **-iu**] | Displays the generation sizes for each heap and the total free space in each generation on each heap. If the -**inclUnrooted** option is specified, the report includes information about the managed objects from the garbage collection heap that is no longer rooted. Only supported on Windows. | +| **HistClear** | Releases any resources used by the family of `Hist` commands.

Generally, you do not have to explicitly call `HistClear`, because each `HistInit` cleans up the previous resources. | +| **HistInit** | Initializes the SOS structures from the stress log saved in the debuggee. | +| **HistObj** ** | Examines all stress log relocation records and displays the chain of garbage collection relocations that may have led to the address passed in as an argument. | +| **HistObjFind** ** | Displays all the log entries that reference an object at the specified address. | +| **HistRoot** *\* | Displays information related to both promotions and relocations of the specified root.

The root value can be used to track the movement of an object through the garbage collections. | +| **IP2MD** (**ip2md**) \<*Code address*> | Displays the `MethodDesc` structure at the specified address in code that has been JIT-compiled. | +| **ListNearObj** (**lno**) ** | Displays the objects preceding and following the specified address. The command looks for the address in the garbage collection heap that looks like a valid beginning of a managed object (based on a valid method table) and the object following the argument address. Only supported on Windows. | +| **MinidumpMode** [**0**] [**1**] | Prevents running unsafe commands when using a minidump.

Pass **0** to disable this feature or **1** to enable this feature. By default, the **MinidumpMode** value is set to **0**.

Minidumps created with the **.dump /m** command or **.dump** command have limited CLR-specific data and allow you to run only a subset of SOS commands correctly. Some commands may fail with unexpected errors because required areas of memory are not mapped or are only partially mapped. This option protects you from running unsafe commands against minidumps.

Only supported with Windbg. | +| **Name2EE** (**name2ee**) \<*module name*> \<*type or method name*>

-or-

**Name2EE** \<*module name*>**!**\<*type or method name*> | Displays the `MethodTable` structure and `EEClass` structure for the specified type or method in the specified module.

The specified module must be loaded in the process.

To get the proper type name, browse the module by using the [Ildasm.exe (IL Disassembler)](../../../docs/framework/tools/ildasm-exe-il-disassembler.md). You can also pass `*` as the module name parameter to search all loaded managed modules. The *module name* parameter can also be the debugger's name for a module, such as `mscorlib` or `image00400000`.

This command supports the Windows debugger syntax of <`module`>`!`<`type`>. The type must be fully qualified. | +| **ObjSize** [\<*Object address*>] | [**-aggregate**] [**-stat**] | Displays the size of the specified object. If you do not specify any parameters, the **ObjSize** command displays the size of all objects found on managed threads, displays all garbage collector handles in the process, and totals the size of any objects pointed to by those handles. The **ObjSize** command includes the size of all child objects in addition to the parent.

The **-aggregate** option can be used in with the **-stat** argument to get a detailed view of the types that are still rooted. By using **!dumpheap -stat** and **!objsize -aggregate -stat**, you can determine which objects are no longer rooted and diagnose various memory issues.

Only supported on Windows. | +| **PrintException** [**-nested**] [**-lines**] [\<*Exception object address*>]

-or-

**PE** [**-nested**] [\<*Exception object address*>] | Displays and formats fields of any object derived from the class at the specified address. If you do not specify an address, the **PrintException** command displays the last exception thrown on the current thread.

The **-nested** option displays details about nested exception objects.

The **-lines** option displays source information, if available.

You can use this command to format and view the `_stackTrace` field, which is a binary array. | +| **ProcInfo** [**-env**] [**-time**] [**-mem**] | Displays environment variables for the process, kernel CPU time, and memory usage statistics. Only supported with Windbg. | +| **RCWCleanupList** \<*RCWCleanupList address*> | Displays the list of runtime callable wrappers at the specified address that are awaiting cleanup. Only supported with Windbg. | +| **SaveModule** \<*Base address*> \<*Filename*> | Writes an image, which is loaded in memory at the specified address, to the specified file. Only supported with Windbg. | +| **SetHostRuntime** [\] | This command sets the path to the .NET runtime to use to host the managed code that runs as part of SOS in the debugger (LLDB). The runtime needs to be at least version 2.1.0 or greater. If there are spaces in directory, it needs to be single-quoted (').

Normally, SOS attempts to find an installed .NET runtime to run its managed code automatically but this command is available if it fails. The default is to use the same runtime (libcoreclr) being debugged. Use this command if the default runtime being debugged isn't working enough to run the SOS code or if the version is less than 2.1.0.

If you received the following error message when running a SOS command, use this command to set the path to 2.1.0 or greater .NET runtime.

`(lldb) clrstack`
`Error: Fail to initialize CoreCLR 80004005 ClrStack failed`

`(lldb) sethostruntime /usr/share/dotnet/shared/Microsoft.NETCore.App/2.1.6`

You can use the "dotnet --info" in a command shell to find the path of an installed .NET runtime. | +| **SetSymbolServer** [**-ms**] [**-disable**] [**-log**] [**-loadsymbols**] [**-cache** \] [**-directory** \] [**-sympath** \] [\] | Enables the symbol server downloading support.

The **-ms** option enables downloading from the public Microsoft symbol server.

The **-disable** option turns on the symbol download support.

The **-cache** \ option specifies a symbol cache directory. The default is $HOME/.dotnet/symbolcache if not specified.

The **-directory** option adds a path to search for symbols. Can be more than one.

The **-sympath** option adds server, cache, and directory paths in the Windows symbol path format.

The **-log** option enables symbol download logging.

The **-loadsymbols** option attempts to download the native .NET symbols for the runtime. Supported on lldb and dotnet-dump. | +| **SOSFlush** | Flushes an internal SOS cache. | +| **SOSStatus** [**-reset**] | Displays internal SOS status or reset the internal cached state. | +| **StopOnException** [**-derived**] [**-create** | **-create2**] \<*Exception*> \<*Pseudo-register number*> | Causes the debugger to stop when the specified exception is thrown, but to continue running when other exceptions are thrown.

The **-derived** option catches the specified exception and every exception that derives from the specified exception.

Only supported with Windbg. | +| **SyncBlk** [**-all** | \<*syncblk number*>] | Displays the specified `SyncBlock` structure or all `SyncBlock` structures. If you do not pass any arguments, the **SyncBlk** command displays the `SyncBlock` structure corresponding to objects that are owned by a thread.

A `SyncBlock` structure is a container for extra information that does not need to be created for every object. It can hold COM interop data, hash codes, and locking information for thread-safe operations. | +| **ThreadPool** | Displays information about the managed thread pool, including the number of work requests in the queue, the number of completion port threads, and the number of timers. | +| **Threads** (**clrthreads**) [**-live**] [**-special**] | Displays all managed threads in the process.

The **Threads** command displays the debugger shorthand ID, the CLR thread ID, and the operating system thread ID. Additionally, the **Threads** command displays a Domain column that indicates the application domain in which a thread is executing, an APT column that displays the COM apartment mode, and an Exception column that displays the last exception thrown in the thread.

The **-live** option displays threads associated with a live thread.

The **-special** option displays all special threads created by the CLR. Special threads include garbage collection threads (in concurrent and server garbage collection), debugger helper threads, finalizer threads, unload threads, and thread pool timer threads.

Supported for Native AOT applications. | +| **ThreadState \<** *State value field* **>** | Displays the state of the thread. The `value` parameter is the value of the `State` field in the **Threads** report output. | +| **Token2EE** \<*module name*> \<*token*> | Turns the specified metadata token in the specified module into a `MethodTable` structure or `MethodDesc` structure.

You can pass `*` for the module name parameter to find what that token maps to in every loaded managed module. You can also pass the debugger's name for a module, such as `mscorlib` or `image00400000`. | +| **U** [**-gcinfo**] [**-ehinfo**] [**-n**] \<*MethodDesc address*> | \<*Code address*> | Displays an annotated disassembly of a managed method specified either by a `MethodDesc` structure pointer for the method or by a code address within the method body. The **U** command displays the entire method from start to finish, with annotations that convert metadata tokens to names.

The **-gcinfo** option causes the **U** command to display the `GCInfo` structure for the method.

The **-ehinfo** option displays exception information for the method. You can also obtain this information with the **EHInfo** command.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS looks up the symbols for every managed frame and, if successful, displays the corresponding source file name and line number. You can specify the **-n** option to disable this behavior. | +| **VerifyHeap** | Checks the garbage collector heap for signs of corruption and displays any errors found.

Heap corruptions can be caused by platform invoke calls that are constructed incorrectly.

Supported for Native AOT applications. | +| **VerifyObj** \<*object address*> | Checks the object that is passed as an argument for signs of corruption. Only supported on Windows. | +| **VMMap** | Traverses the virtual address space and displays the type of protection applied to each region. Only supported with Windbg. | +| **VMStat** | Provides a summary view of the virtual address space, ordered by each type of protection applied to that memory (free, reserved, committed, private, mapped, image). The TOTAL column displays the result of the AVERAGE column multiplied by the BLK COUNT column. Only supported with Windbg. | + +### Windows Debugger + +You can also use the .NET debugger extensions by loading it into the [WinDbg/dbg debugger](/windows-hardware/drivers/debugger/debugger-download-tools) and executing commands within the Windows debugger. The commands can be used on live processes or dumps. + +Windbg should load the extension automatically whenever the process being debugged contains the .NET runtime (coreclr.dll or libcoreclr.so). + +### LLDB Debugger + +For instructions on configuring the .NET debugger extensions for LLDB, see [dotnet-debugger-extensions](dotnet-debugger-extensions.md). The commands can be used on live processes or dumps. + +By default you can reach all the commands by entering: `sos [command_name]`. However, the common commands have been aliased so that you don't need the `sos` prefix: + +| Command | Function | +| ------------------------------------- | ------------------------------------------------------------------------------------------- | +| `analyzeoom` | Displays the info of the last OOM that occurred on an allocation request to the GC heap. | +| `bpmd` | Creates a breakpoint at the specified managed method in the specified module. | +| `clrmodules` | Lists the managed modules in the process. | +| `clrstack` | Provides a stack trace of managed code only. | +| `clrthreads` | Lists the managed threads that are running. | +| `clru` | Displays an annotated disassembly of a managed method. | +| `dbgout` | Enables/disables (`-off`) internal SOS logging. | +| `dso` | Displays all managed objects found within the bounds of the current stack. | +| `dumpalc` | Displays details about a collectible AssemblyLoadContext to which the specified object is loaded. | +| `dumparray` | Displays details about a managed array. | +| `dumpasync` | Displays info about async state machines on the garbage-collected heap. | +| `dumpassembly` | Displays details about an assembly. | +| `dumpclass` | Displays information about the `EEClass` structure at the specified address. | +| `dumpconcurrentdictionary` | Displays concurrent dictionary content. | +| `dumpconcurrentqueue` | Displays concurrent queue content. | +| `dumpdelegate` | Displays information about a delegate. | +| `dumpdomain` | Displays information about the all assemblies within all the AppDomains or the specified one. | +| `dumpgcdata` | Displays information about the GC data. | +| `dumpgen` | Displays heap content for the specified generation. | +| `dumpheap` | Displays info about the garbage-collected heap and collection statistics about objects. | +| `dumpil` | Displays the common intermediate language (CIL) that's associated with a managed method. | +| `dumplock` | Displays information about System.Threading.Lock objects, such as those being held by threads (default), or those being waited upon by threads. This command is available in [.NET debugger extensions](dotnet-debugger-extensions.md) only. | +| `dumplog` | Writes the contents of an in-memory stress log to the specified file. | +| `dumpmd` | Displays information about the `MethodDesc` structure at the specified address. | +| `dumpmodule` | Displays information about the module at the specified address. | +| `dumpmt` | Displays information about the method table at the specified address. | +| `dumpobj` | Displays info the object at the specified address. | +| `dumpruntimetypes` | Finds all System.RuntimeType objects in the GC heap and prints the type name and MethodTable they refer too. | +| `dumpsig` | Dumps the signature of a method or field specified by ` `. | +| `dumpsigelem` | Dumps a single element of a signature object. | +| `dumpstack` | Displays a native and managed stack trace. | +| `dumpstackobjects` | Displays all managed objects found within the bounds of the current stack. | +| `dumpvc` | Displays info about the fields of a value class. | +| `eeheap` | Displays info about process memory consumed by internal runtime data structures. | +| `eestack` | Runs `dumpstack` on all threads in the process. | +| `eeversion` | Displays information about the runtime and SOS versions. | +| `ehinfo` | Displays the exception handling blocks in a JIT-ed method. | +| `finalizequeue` | Displays all objects registered for finalization. | +| `findappdomain` | Attempts to resolve the AppDomain of a GC object. | +| `findroots` | Finds and displays object roots across GC collections. | +| `gchandles` | Displays statistics about garbage collector handles in the process. | +| `gcheapstat` | Displays statistics about garbage collector. | +| `gcinfo` | Displays the JIT GC encoding for a method. | +| `gcroot` | Displays info about references (or roots) to the object at the specified address. | +| `gcwhere` | Displays the location in the GC heap of the specified address. | +| `histclear` | Releases any resources used by the family of Hist commands. | +| `histinit` | Initializes the SOS structures from the stress log saved in the debuggee. | +| `histobj` | Examines all stress log relocation records and displays the chain of garbage collection relocations that may have led to the address passed in as an argument. | +| `histobjfind` | Displays all the log entries that reference the object at the specified address. | +| `histroot` | Displays information related to both promotions and relocations of the specified root. | +| `histstats` | Displays stress log stats. | +| `ip2md` | Displays the `MethodDesc` structure at the specified address in code that has been JIT-compiled. | +| `listnearobj` | Displays the object preceding and succeeding the specified address. | +| `loadsymbols` | Loads the .NET native module symbols. | +| `logging` | Enables/disables internal SOS logging. | +| `name2ee` | Displays the `MethodTable` and `EEClass` structures for the specified type or method in the specified module. | +| `objsize` | Displays the size of the specified object. | +| `parallelstacks` | Displays the merged threads stack similarly to the Visual Studio 'Parallel Stacks' panel. | +| `pathto` | Displays the GC path from `` to ``. | +| `pe` | Displays and formats fields of any object derived from the class at the specified address. | +| `printexception` | Displays and formats fields of any object derived from the class at the specified address. | +| `runtimes` | Lists the runtimes in the target or change the default runtime. | +| `stoponcatch` | Target process will break the next time a managed exception is caught during execution. | +| `setclrpath` | Sets the path to load coreclr dac/dbi files. `setclrpath `. | +| `sethostruntime` | Sets or displays the .NET runtime directory to use to run managed code in SOS. | +| `setsymbolserver` | Enables the symbol server support. | +| `setsostid` | Sets the current OS tid/thread index instead of using the one LLDB provides. `setsostid `. | +| `sos` | Executes various coreclr debugging commands. Use the syntax `sos `. For more information, see 'soshelp'. | +| `soshelp` | Displays all available commands when no parameter is specified, or displays detailed help information about the specified command: `soshelp `. | +| `syncblk` | Displays the SyncBlock holder info. | +| `taskstate` | Displays a Task state in a human readable format. | +| `threadpool` | Displays info about the runtime thread pool. | +| `threadpoolqueue` | Displays queued thread pool work items. | +| `threadstate` | Pretty prints the meaning of a threads state. | +| `timerinfo` | Displays information about running timers. | +| `token2ee` | Displays the MethodTable structure and MethodDesc structure for the specified token and module. | +| `traverseheap` | Writes out heap information to a file in a format understood by the CLR Profiler. | +| `verifyheap` | Checks the GC heap for signs of corruption. | +| `verifyobj` | Checks the object that is passed as an argument for signs of corruption. | + +## Windbg/cdb example usage + +| Command | Description | +| - | - | +| `!dumparray -start 2 -length 5 -details 00ad28d0` | Displays the contents of an array at the address `00ad28d0`. The display starts from the second element and continues for five elements. | +| `!dumpassembly 1ca248` | Displays the contents of an assembly at the address `1ca248`. | +| `!dumpheap` | Displays information about the garbage collector heap. | +| `!DumpLog` | Writes the contents of the in-memory stress log to a (default) file called StressLog.txt in the current directory. | +| `!dumpmd 902f40` | Displays the `MethodDesc` structure at the address `902f40`. | +| `!dumpmodule 1caa50` | Displays information about a module at the address `1caa50`. | +| `!DumpObj a79d40` | Displays information about an object at the address `a79d40`. | +| `!DumpVC 0090320c 00a79d9c` | Displays the fields of a value class at the address `00a79d9c` using the method table at the address `0090320c`. | +| `!eeheap` -gc | Displays the process memory used by the garbage collector. | +| `!finalizequeue` | Displays all objects scheduled for finalization. | +| `!findappdomain 00a79d98` | Determines the application domain of an object at the address `00a79d98`. | +| `!gcinfo 5b68dbb8` | Displays all garbage collector handles in the current process. | +| `!name2ee unittest.exe MainClass.Main` | Displays the `MethodTable` and `EEClass` structures for the `Main` method in the class `MainClass` in the module `unittest.exe`. | +| `!token2ee unittest.exe 02000003` | Displays information about the metadata token at the address `02000003` in the module `unittest.exe`. | + +## LLDB example usage + +| Command | Description | +| - | - | +| `dumparray -start 2 -length 5 -details 00ad28d0` | Displays the contents of an array at the address `00ad28d0`. The display starts from the second element and continues for five elements. | +| `dumpassembly 1ca248` | Displays the contents of an assembly at the address `1ca248`. | +| `dumpheap` | Displays information about the garbage collector heap. | +| `dumplog` | Writes the contents of the in-memory stress log to a (default) file called StressLog.txt in the current directory. | +| `dumpmd 902f40` | Displays the `MethodDesc` structure at the address `902f40`. | +| `dumpmodule 1caa50` | Displays information about a module at the address `1caa50`. | +| `dumpobj a79d40` | Displays information about an object at the address `a79d40`. | +| `dumpvc 0090320c 00a79d9c` | Displays the fields of a value class at the address `00a79d9c` using the method table at the address `0090320c`. | +| `eeheap -gc` | Displays the process memory used by the garbage collector. | +| `findappdomain 00a79d98` | Determines the application domain of an object at the address `00a79d98`. | +| `gcinfo 5b68dbb8` | Displays all garbage collector handles in the current process. | +| `name2ee unittest.exe MainClass.Main` | Displays the `MethodTable` and `EEClass` structures for the `Main` method in the class `MainClass` in the module `unittest.exe`. | +| `token2ee unittest.exe 02000003` | Displays information about the metadata token at the address `02000003` in the module `unittest.exe`. | +| `clrthreads` | Displays the managed threads. | + +## See also + +- [An introduction to dumps in .NET](dumps.md) +- [Learn how to debug a memory leak in .NET](debug-memory-leak.md) +- [Collecting and analyzing memory dumps blog](https://devblogs.microsoft.com/dotnet/collecting-and-analyzing-memory-dumps/) +- [Dump analysis tool (dotnet-dump)](dotnet-dump.md) +- [.NET debugger extensions installer (dotnet-debugger-extensions)](dotnet-debugger-extensions.md) +- [Heap analysis tool (dotnet-gcdump)](dotnet-gcdump.md) diff --git a/docs/core/diagnostics/dotnet-debugger-extensions.md b/docs/core/diagnostics/dotnet-debugger-extensions.md new file mode 100644 index 0000000000000..e38611726e782 --- /dev/null +++ b/docs/core/diagnostics/dotnet-debugger-extensions.md @@ -0,0 +1,80 @@ +--- +title: dotnet-debugger-extensions diagnostic tool - .NET CLI +description: Learn how to install and use the dotnet-debugger-extensions CLI tool to manage the .NET debugging extensions, which is used with native debuggers on Windows and Linux. +ms.date: 11/17/2020 +ms.topic: reference +ms.custom: linux-related-content +--- +# .NET debugger extensions installer (dotnet-debugger-extensions) + +**This article applies to:** ✔️ .NET 6.0 SDK and later versions + +## Install + +To install the latest release version of the `dotnet-debugger-extensions` [NuGet package](https://www.nuget.org/packages/dotnet-debugger-extensions), use the [dotnet tool install](../tools/dotnet-tool-install.md) command: + + ```dotnetcli + dotnet tool install --global dotnet-debugger-extensions + ``` + +## Synopsis + +```console +dotnet-debugger-extensions [-h|--help] [options] [command]] +``` + +## Description + +The `dotnet-debugger-extensions` global tool installs the [.NET debugger extensions](debugger-extensions.md), which enable better debugging experience in native debuggers like WinDbg and LLDB. + +> [!NOTE] +> The Windows Debugger (>= version 10.0.18317.1001 of WinDbg or cdb) automatically loads the extensions from the Microsoft extension gallery. + +## Options + +- **`--version`** + + Displays version information. + +- **`-h|--help`** + + Shows command-line help. + +## dotnet-debugger-extensions install + +Installs the [.NET debugger extensions](debugger-extensions.md) locally for debugging .NET Core processes. On macOS and Linux, the *.lldbinit* file is updated so that the extension automatically loads at LLDB startup. If you're installing on Windows with older debugging tools (before version 10.0.18317.1001), you need to manually load the extension in WinDbg or cdb by running `.load %USERPROFILE%\.dotnet\sos\sos.dll` in the debugger. + +This overwrites any previous installations from the dotnet-debugger-extensions or dotnet-sos installers. + +### Synopsis + +```console +dotnet-debugger-extensions install [--architecture ] +``` + +### Options + +- **`--architecture `** + + Specifies the processor architecture of the extension binaries to install. By default, `dotnet-debugger-extensions` installs the architecture of the host machine. Use this option when you want to install for an architecture that's different from the dotnet host architecture. For example, if you're running Arm32 binaries from an Arm64 host, you need to install with `dotnet-debugger-extensions install --architecture Arm`. + + The following architectures are available: + + - `Arm` + - `Arm64` + - `X86` + - `X64` + +- **`--accept-license-agreement`** + + This option accepts and agrees to the licensing agreement without manual keyboard interaction. For use when console input is redirected. + +## dotnet-debugger-extensions uninstall + +Uninstalls the [.NET debugger extensions](debugger-extensions.md) and, on Linux and macOS, removes it from LLDB configuration. + +### Synopsis + +```console +dotnet-debugger-extensions uninstall +``` diff --git a/docs/core/diagnostics/dotnet-sos.md b/docs/core/diagnostics/dotnet-sos.md index 7b182c9e8485f..03574c83fd307 100644 --- a/docs/core/diagnostics/dotnet-sos.md +++ b/docs/core/diagnostics/dotnet-sos.md @@ -7,7 +7,10 @@ ms.custom: linux-related-content --- # SOS installer (dotnet-sos) -**This article applies to:** ✔️ .NET Core 2.1 SDK and later versions +**This article applies to:** ✔️ .NET 6.0 SDK and later versions + +> [!NOTE] +Consider using the [.NET debugger extensions](dotnet-debugger-extensions.md) instead, which include the SOS functionality and additional features. ## Install @@ -38,10 +41,7 @@ dotnet-sos [-h|--help] [options] [command]] ## Description -The `dotnet-sos` global tool installs the [SOS debugger extension](sos-debugging-extension.md). This extension lets you inspect managed .NET Core state from native debuggers like lldb and windbg. - -> [!NOTE] -> Installing SOS via the `dotnet-sos` tool is only needed on Linux or macOS. It may also be needed on Windows if you're using older debugging tools. Recent versions of the [Windows Debugger](/windows-hardware/drivers/debugger/debugger-download-tools) (>= version 10.0.18317.1001 of WinDbg or cdb) load SOS automatically from the Microsoft extension gallery. +The `dotnet-sos` global tool installs the [SOS debugger extension](sos-debugging-extension.md). This extension lets you inspect managed .NET Core state from native debuggers like LLDB and WinDbg. ## Options @@ -55,7 +55,9 @@ The `dotnet-sos` global tool installs the [SOS debugger extension](sos-debugging ## dotnet-sos install -Installs the [SOS extension](sos-debugging-extension.md) locally for debugging .NET Core processes. On macOS and Linux, the *.lldbinit* file will be updated so that the extension automatically loads at lldb startup. If you're installing SOS on Windows with older debugging tools (prior to version 10.0.18317.1001), you will need to manually load the extension in WinDbg or cdb by running `.load %USERPROFILE%\.dotnet\sos\sos.dll` in the debugger. +Installs the [SOS extension](sos-debugging-extension.md) locally for debugging .NET Core processes. On macOS and Linux, the *.lldbinit* file is updated so that the extension automatically loads at LLDB startup. If you're installing SOS on Windows with older debugging tools (before version 10.0.18317.1001), you need to manually load the extension in WinDbg or cdb by running `.load %USERPROFILE%\.dotnet\sos\sos.dll` in the debugger. + +This overwrites any previous installations from the dotnet-debugger-extensions or dotnet-sos installers. ### Synopsis @@ -67,7 +69,7 @@ dotnet-sos install [--architecture ] - **`--architecture `** - Specifies the processor architecture of the SOS binaries to install. By default, `dotnet-sos` installs the architecture of the host machine. Use this option when you want to install SOS for an architecture that's different from the dotnet host architecture. For example, if you're running Arm32 binaries from an Arm64 host, you will need to install SOS with `dotnet-sos install --architecture Arm`. + Specifies the processor architecture of the SOS binaries to install. By default, `dotnet-sos` installs the architecture of the host machine. Use this option when you want to install SOS for an architecture that's different from the dotnet host architecture. For example, if you're running Arm32 binaries from an Arm64 host, you need to install SOS with `dotnet-sos install --architecture Arm`. The following architectures are available: @@ -78,7 +80,7 @@ dotnet-sos install [--architecture ] ## dotnet-sos uninstall -Uninstalls the [SOS extension](sos-debugging-extension.md) and, on Linux and macOS, removes it from lldb configuration. +Uninstalls the [SOS extension](sos-debugging-extension.md) and, on Linux and macOS, removes it from LLDB configuration. ### Synopsis diff --git a/docs/core/diagnostics/sos-debugging-extension.md b/docs/core/diagnostics/sos-debugging-extension.md index 3f85bdcca865f..b78f1847bce37 100644 --- a/docs/core/diagnostics/sos-debugging-extension.md +++ b/docs/core/diagnostics/sos-debugging-extension.md @@ -32,15 +32,15 @@ The following table of commands is also available under **Help** or **soshelp**. | Command | Description | |---------|-------------| -| **bpmd** [**-nofuturemodule**] [\<*module name*> \<*method name*>] [**-md** <`MethodDesc`>] **-list** **-clear** \<*pending breakpoint number*> **-clearall** | Creates a breakpoint at the specified method in the specified module.

If the specified module and method have not been loaded, this command waits for a notification that the module was loaded and just-in-time (JIT) compiled before creating a breakpoint.

You can manage the list of pending breakpoints by using the **-list**, **-clear**, and **-clearall** options:

The **-list** option generates a list of all the pending breakpoints. If a pending breakpoint has a non-zero module ID, that breakpoint is specific to a function in that particular loaded module. If the pending breakpoint has a zero module ID, that breakpoint applies to modules that have not yet been loaded.

Use the **-clear** or **-clearall** option to remove pending breakpoints from the list. | -| **CLRStack** [**-a**] [**-l**] [**-p**] [**-n**] [**-f**] [**-r**] [**-all**] | Provides a stack trace of managed code only.

The **-p** option shows arguments to the managed function.

The **-l** option shows information on local variables in a frame. The SOS debugging extension cannot retrieve local names, so the output for local names is in the format \<*local address*> **=** \<*value*>.

The **-a** option is a shortcut for **-l** and **-p** combined.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS will look up the symbols for every managed frame and if successful will display the corresponding source file name and line number. The **-n** (No line numbers) parameter can be specified to disable this behavior.

The **-f** option (full mode) displays the native frames intermixing them with the managed frames and the assembly name and function offset for the managed frames. This option does not display native frames when used with `dotnet-dump`.

The **-r** option dumps the registers for each stack frame.

The **-all** option dumps all the managed threads' stacks. | +| **bpmd** [**-nofuturemodule**] [\<*module name*> \<*method name*>] [**-md** <`MethodDesc`>] **-list** **-clear** \<*pending breakpoint number*> **-clearall** | Creates a breakpoint at the specified method in the specified module.

If the specified module and method have not been loaded, this command waits for a notification that the module was loaded and just-in-time (JIT) compiled before creating a breakpoint.

You can manage the list of pending breakpoints by using the **-list**, **-clear**, and **-clearall** options:

The **-list** option generates a list of all the pending breakpoints. If a pending breakpoint has a nonzero module ID, that breakpoint is specific to a function in that particular loaded module. If the pending breakpoint has a zero module ID, that breakpoint applies to modules that have not yet been loaded.

Use the **-clear** or **-clearall** option to remove pending breakpoints from the list. | +| **CLRStack** [**-a**] [**-l**] [**-p**] [**-n**] [**-f**] [**-r**] [**-all**] | Provides a stack trace of managed code only.

The **-p** option shows arguments to the managed function.

The **-l** option shows information on local variables in a frame. The SOS debugging extension cannot retrieve local names, so the output for local names is in the format \<*local address*> **=** \<*value*>.

The **-a** option is a shortcut for **-l** and **-p** combined.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS will look up the symbols for every managed frame and if successful will display the corresponding source file name and line number. The **-n** (No line numbers) parameter can be specified to disable this behavior.

The **-f** option (full mode) displays the native frames intermixing them with the managed frames and the assembly name and function offset for the managed frames. This option does not display native frames when used with `dotnet-dump`.

The **-r** option dumps the registers for each stack frame.

The **-all** option dumps all the managed threads' stacks. | | **COMState** | Lists the COM apartment model for each thread and a `Context` pointer, if available. This command is only supported on Windows. | | **DumpArray** [**-start** \<*startIndex*>] [**-length** \<*length*>] [**-details**] [**-nofields**] \<*array object address*>

-or-

**DA** [**-start** \<*startIndex*>] [**-length** \<*length*>] [**-details**] [**-nofields**] *array object address*> | Examines elements of an array object.

The **-start** option specifies the starting index at which to display elements.

The **-length** option specifies how many elements to show.

The **-details** option displays details of the element using the **DumpObj** and **DumpVC** formats.

The **-nofields** option prevents arrays from displaying. This option is available only when the **-details** option is specified. | -| **DumpAsync** (**dumpasync**) [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [**-waiting**] [**-roots**] | DumpAsync traverses the garbage collected heap and looks for objects representing async state machines as created when an async method's state is transferred to the heap. This command recognizes async state machines defined as `async void`, `async Task`, `async Task`, `async ValueTask`, and `async ValueTask`.

The output includes a block of details for each async state machine object found. These details include:
- A line for the type of the async state machine object, including its MethodTable address, its object address, its size, and its type name.
- A line for the state machine type name as contained in the object.
- A listing of each field on the state machine.
- A line for a continuation from this state machine object, if one or more has been registered.
- Discovered GC roots for this async state machine object. | +| **DumpAsync** (**dumpasync**) [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [**-waiting**] [**-roots**] | DumpAsync traverses the garbage collected heap and looks for objects representing async state machines as created when an async method's state is transferred to the heap. This command recognizes async state machines defined as `async void`, `async Task`, `async Task`, `async ValueTask`, and `async ValueTask`.

The output includes a block of details for each async state machine object found. These details include:
- A line for the type of the async state machine object, including its MethodTable address, its object address, its size, and its type name.
- A line for the state machine type name as contained in the object.
- A listing of each field on the state machine.
- A line for a continuation from this state machine object, if one or more has been registered.
- Discovered GC roots for this async state machine object. | | **DumpAssembly** \<*assembly address*> | Displays information about an assembly.

The **DumpAssembly** command lists multiple modules, if they exist.

You can get an assembly address by using the **DumpDomain** command. | | **DumpClass** \<*EEClass address*> | Displays information about the `EEClass` structure associated with a type.

The **DumpClass** command displays static field values but does not display nonstatic field values.

Use the **DumpMT**, **DumpObj**, **Name2EE**, or **Token2EE** command to get an `EEClass` structure address. | -| **DumpDomain** [\<*domain address*>] | Enumerates each object that's loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process. Since .NET (Core) only has one , **DumpDomain** only returns one object. | -| **DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]] | Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes.

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes.

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address. | +| **DumpDomain** [\<*domain address*>] | Enumerates each object that's loaded within the specified object address. When called with no parameters, the **DumpDomain** command lists all objects in a process. Since .NET (Core) only has one , **DumpDomain** only returns one object. | +| **DumpHeap** [**-stat**] [**-strings**] [**-short**] [**-min** \<*size*>] [**-max** \<*size*>] [**-thinlock**] [**-startAtLowerBound**] [**-mt** \<*MethodTable address*>] [**-type** \<*partial type name*>] [*start* [*end*]] | Displays information about the garbage-collected heap and collection statistics about objects.

The **DumpHeap** command displays a warning if it detects excessive fragmentation in the garbage collector heap.

The **-stat** option restricts the output to the statistical type summary.

The **-strings** option restricts the output to a statistical string value summary.

The **-short** option limits output to just the address of each object. This lets you easily pipe output from the command to another debugger command for automation.

The **-min** option ignores objects that are less than the `size` parameter, specified in bytes.

The **-max** option ignores objects that are larger than the `size` parameter, specified in bytes.

The **-thinlock** option reports ThinLocks. For more information, see the **SyncBlk** command.

The `-startAtLowerBound` option forces the heap walk to begin at the lower bound of a supplied address range. During the planning phase, the heap is often not walkable because objects are being moved. This option forces **DumpHeap** to begin its walk at the specified lower bound. You must supply the address of a valid object as the lower bound for this option to work. You can display memory at the address of a bad object to manually find the next method table. If the garbage collection is currently in a call to `memcopy`, you may also be able to find the address of the next object by adding the size to the start address, which is supplied as a parameter.

The **-mt** option lists only those objects that correspond to the specified `MethodTable` structure.

The **-type** option lists only those objects whose type name is a substring match of the specified string.

The `start` parameter begins listing from the specified address.

The `end` parameter stops listing at the specified address. | | **DumpIL** \<*Managed DynamicMethod object*> | \<*DynamicMethodDesc pointer*> | \<*MethodDesc pointer*> | Displays the common intermediate language (CIL) that's associated with a managed method.

Dynamic CIL is emitted differently than CIL that's loaded from an assembly. Dynamic CIL refers to objects in a managed object array rather than to metadata tokens. | | **DumpLog** [**-addr** \<*addressOfStressLog*>] [<*Filename*>] | Writes the contents of an in-memory stress log to the specified file. If you do not specify a name, this command creates a file called StressLog.txt in the current directory.

The in-memory stress log helps you diagnose stress failures without using locks or I/O. To enable the stress log, set the following registry keys under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\\.NETFramework:

(DWORD) StressLog = 1

(DWORD) LogFacility = 0xffffffff

(DWORD) StressLogSize = 65536

The optional `-addr` option lets you specify a stress log other than the default log. | | **DumpMD** \<*MethodDesc address*> | Displays information about a `MethodDesc` structure at the specified address.

You can use the **IP2MD** command to get the `MethodDesc` structure address from a managed function. | @@ -51,12 +51,12 @@ The following table of commands is also available under **Help** or **soshelp**. | **DumpStack** [**-EE**] [**-n**] [`top` *stack* [`bottom` *stack*]] | Displays a stack trace.

The **-EE** option causes the **DumpStack** command to display only managed functions. Use the `top` and `bottom` parameters to limit the stack frames displayed on x86 platforms.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS will look up the symbols for every managed frame and if successful will display the corresponding source file name and line number. The **-n** (No line numbers) parameter can be specified to disable this behavior. | | **DumpSig** \<*sigaddr*> \<*moduleaddr*> | Displays information about a `Sig` structure at the specified address. | | **DumpSigElem** \<*sigaddr*> \<*moduleaddr*> | Displays a single element of a signature object. In most cases, you should use **DumpSig** to look at individual signature objects. However, if a signature has been corrupted in some way, you can use **DumpSigElem** to read the valid portions of it. | -| **DumpStackObjects** [**-verify**] [`top` *stack* [`bottom` *stack*]]

-or-

**DSO** [**-verify**] [`top` *stack* [`bottom` *stack*]] | Displays all managed objects found within the bounds of the current stack.

The **-verify** option validates each non-static `CLASS` field of an object field.

Use the **DumpStackObject** command with stack tracing commands such as **K** (windbg) or **bt** (lldb) along with the **clrstack** command to determine the values of local variables and parameters. | +| **DumpStackObjects** [**-verify**] [`top` *stack* [`bottom` *stack*]]

-or-

**DSO** [**-verify**] [`top` *stack* [`bottom` *stack*]] | Displays all managed objects found within the bounds of the current stack.

The **-verify** option validates each nonstatic `CLASS` field of an object field.

Use the **DumpStackObject** command with stack tracing commands such as **K** (windbg) or **bt** (lldb) along with the **clrstack** command to determine the values of local variables and parameters. | | **DumpVC** \<*MethodTable address*> \<*Address*> | Displays information about the fields of a value class at the specified address.

The **MethodTable** parameter allows the **DumpVC** command to correctly interpret fields. Value classes do not have a method table as their first field. | -| **EEHeap** [**-gc**] [**-loader**] | Displays information about process memory consumed by internal runtime data structures.

The **-gc** and **-loader** options limit the output of this command to garbage collector or loader data structures.

The information for the garbage collector lists the ranges of each segment in the managed heap. If the pointer falls within a segment range given by **-gc**, the pointer is an object pointer. | +| **EEHeap** [**-gc**] [**-loader**] | Displays information about process memory consumed by internal runtime data structures.

The **-gc** and **-loader** options limit the output of this command to garbage collector or loader data structures.

The information for the garbage collector lists the ranges of each segment in the managed heap. If the pointer falls within a segment range given by **-gc**, the pointer is an object pointer. | | **EEStack** [**-short**] [**-EE**] | Runs the **DumpStack** command on all threads in the process.

The **-EE** option is passed directly to the **DumpStack** command. The **-short** parameter limits the output to the following kinds of threads:

Threads that have taken a lock.

Threads that have been stalled in order to allow a garbage collection.

Threads that are currently in managed code. | -| **EHInfo** [\<*MethodDesc address*>] [\<*Code address*>] | Displays the exception handling blocks in a specified method. This command displays the code addresses and offsets for the clause block (the `try` block) and the handler block (the `catch` block). | -| **FAQ** | Displays frequently asked questions. Not supported in `dotnet-dump`. | +| **EHInfo** [\<*MethodDesc address*>] [\<*Code address*>] | Displays the exception handling blocks in a specified method. This command displays the code addresses and offsets for the clause block (the `try` block) and the handler block (the `catch` block). | +| **FAQ** | Displays frequently asked questions. Not supported in `dotnet-dump`. | | **FinalizeQueue** [**-detail**] | [**-allReady**] [**-short**] | Displays all objects registered for finalization.

The **-detail** option displays extra information about any `SyncBlocks` that need to be cleaned up, and any `RuntimeCallableWrappers` (RCWs) that await cleanup. Both of these data structures are cached and cleaned up by the finalizer thread when it runs.

The `-allReady` option displays all objects that are ready for finalization, regardless of whether they are already marked by the garbage collection as such, or will be marked by the next garbage collection. The objects that are in the "ready for finalization" list are finalizable objects that are no longer rooted. This option can be very expensive, because it verifies whether all the objects in the finalizable queues are still rooted.

The `-short` option limits the output to the address of each object. If it is used in conjunction with **-allReady**, it enumerates all objects that have a finalizer that are no longer rooted. If it is used independently, it lists all objects in the finalizable and "ready for finalization" queues. | | **FindAppDomain** \<*Object address*> | Determines the application domain of an object at the specified address. | | **FindRoots** **-gen** \<*N*> | **-gen any** |\<*object address*> | Causes the debugger to break in the debuggee on the next collection of the specified generation. The effect is reset as soon as the break occurs. To break on the next collection, you have to reissue the command. The *\* form of this command is used after the break caused by the **-gen** or **-gen any** has occurred. At that time, the debuggee is in the right state for **FindRoots** to identify roots for objects from the current condemned generations. Only supported on Windows. | @@ -86,9 +86,9 @@ The following table of commands is also available under **Help** or **soshelp**. | **SOSFlush** | Flushes an internal SOS cache. | | **SOSStatus** [**-reset**] | Displays internal SOS status or reset the internal cached state. | | **StopOnException** [**-derived**] [**-create** | **-create2**] \<*Exception*> \<*Pseudo-register number*> | Causes the debugger to stop when the specified exception is thrown, but to continue running when other exceptions are thrown.

The **-derived** option catches the specified exception and every exception that derives from the specified exception.

Only supported with Windbg. | -| **SyncBlk** [**-all** | \<*syncblk number*>] | Displays the specified `SyncBlock` structure or all `SyncBlock` structures. If you do not pass any arguments, the **SyncBlk** command displays the `SyncBlock` structure corresponding to objects that are owned by a thread.

A `SyncBlock` structure is a container for extra information that does not need to be created for every object. It can hold COM interop data, hash codes, and locking information for thread-safe operations. | +| **SyncBlk** [**-all** | \<*syncblk number*>] | Displays the specified `SyncBlock` structure or all `SyncBlock` structures. If you do not pass any arguments, the **SyncBlk** command displays the `SyncBlock` structure corresponding to objects that are owned by a thread.

A `SyncBlock` structure is a container for extra information that does not need to be created for every object. It can hold COM interop data, hash codes, and locking information for thread-safe operations. | | **ThreadPool** | Displays information about the managed thread pool, including the number of work requests in the queue, the number of completion port threads, and the number of timers. | -| **Threads** (**clrthreads**) [**-live**] [**-special**] | Displays all managed threads in the process.

The **Threads** command displays the debugger shorthand ID, the CLR thread ID, and the operating system thread ID. Additionally, the **Threads** command displays a Domain column that indicates the application domain in which a thread is executing, an APT column that displays the COM apartment mode, and an Exception column that displays the last exception thrown in the thread.

The **-live** option displays threads associated with a live thread.

The **-special** option displays all special threads created by the CLR. Special threads include garbage collection threads (in concurrent and server garbage collection), debugger helper threads, finalizer threads, unload threads, and thread pool timer threads. | +| **Threads** (**clrthreads**) [**-live**] [**-special**] | Displays all managed threads in the process.

The **Threads** command displays the debugger shorthand ID, the CLR thread ID, and the operating system thread ID. Additionally, the **Threads** command displays a Domain column that indicates the application domain in which a thread is executing, an APT column that displays the COM apartment mode, and an Exception column that displays the last exception thrown in the thread.

The **-live** option displays threads associated with a live thread.

The **-special** option displays all special threads created by the CLR. Special threads include garbage collection threads (in concurrent and server garbage collection), debugger helper threads, finalizer threads, unload threads, and thread pool timer threads. | | **ThreadState \<** *State value field* **>** | Displays the state of the thread. The `value` parameter is the value of the `State` field in the **Threads** report output. | | **Token2EE** \<*module name*> \<*token*> | Turns the specified metadata token in the specified module into a `MethodTable` structure or `MethodDesc` structure.

You can pass `*` for the module name parameter to find what that token maps to in every loaded managed module. You can also pass the debugger's name for a module, such as `mscorlib` or `image00400000`. | | **U** [**-gcinfo**] [**-ehinfo**] [**-n**] \<*MethodDesc address*> | \<*Code address*> | Displays an annotated disassembly of a managed method specified either by a `MethodDesc` structure pointer for the method or by a code address within the method body. The **U** command displays the entire method from start to finish, with annotations that convert metadata tokens to names.

The **-gcinfo** option causes the **U** command to display the `GCInfo` structure for the method.

The **-ehinfo** option displays exception information for the method. You can also obtain this information with the **EHInfo** command.

The **-n** option disables the display of source file names and line numbers. If the debugger has the option SYMOPT_LOAD_LINES specified, SOS looks up the symbols for every managed frame and, if successful, displays the corresponding source file name and line number. You can specify the **-n** option to disable this behavior. | @@ -105,8 +105,6 @@ For a list of available SOS commands with `dotnet-dump analyze`, see [dotnet-dum You can also use the SOS debugging extension by loading it into the [WinDbg/dbg debugger](/windows-hardware/drivers/debugger/debugger-download-tools) and executing commands within the Windows debugger. SOS commands can be used on live processes or dumps. -Windbg should load the SOS extension automatically whenever the process being debugged contains the .NET runtime (coreclr.dll or libcoreclr.so). - ### LLDB Debugger For instructions on configuring SOS for LLDB, see [dotnet-sos](dotnet-sos.md). SOS commands can be used on live processes or dumps. @@ -208,7 +206,7 @@ By default you can reach all the SOS commands by entering: `sos [command_name]`. | `!DumpVC 0090320c 00a79d9c` | Displays the fields of a value class at the address `00a79d9c` using the method table at the address `0090320c`. | | `!eeheap` -gc | Displays the process memory used by the garbage collector. | | `!finalizequeue` | Displays all objects scheduled for finalization. | -| `!findappdomain 00a79d98` | Determines the application domain of an object at the address `00a79d98`. | +| `!findappdomain 00a79d98` | Determines the application domain of an object at the address `00a79d98`. | | `!gcinfo 5b68dbb8` | Displays all garbage collector handles in the current process. | | `!name2ee unittest.exe MainClass.Main` | Displays the `MethodTable` and `EEClass` structures for the `Main` method in the class `MainClass` in the module `unittest.exe`. | | `!token2ee unittest.exe 02000003` | Displays information about the metadata token at the address `02000003` in the module `unittest.exe`. | @@ -217,7 +215,7 @@ By default you can reach all the SOS commands by entering: `sos [command_name]`. | Command | Description | | - | - | -| `dumparray -start 2 -length 5 -details 00ad28d0` | Displays the contents of an array at the address `00ad28d0`. The display starts from the second element and continues for five elements. | +| `dumparray -start 2 -length 5 -details 00ad28d0` | Displays the contents of an array at the address `00ad28d0`. The display starts from the second element and continues for five elements. | | `dumpassembly 1ca248` | Displays the contents of an assembly at the address `1ca248`. | | `dumpheap` | Displays information about the garbage collector heap. | | `dumplog` | Writes the contents of the in-memory stress log to a (default) file called StressLog.txt in the current directory. | diff --git a/docs/core/diagnostics/tools-overview.md b/docs/core/diagnostics/tools-overview.md index 43a87d25cd4d2..5ab847b2ccacb 100644 --- a/docs/core/diagnostics/tools-overview.md +++ b/docs/core/diagnostics/tools-overview.md @@ -50,9 +50,9 @@ The [dotnet-stack](dotnet-stack.md) tool allows you to quickly print the managed [dotnet-symbol](dotnet-symbol.md) downloads files (for example, symbols, DAC/DBI, and host files) needed to open a core dump or minidump. Use this tool if you need symbols and modules to debug a dump file captured on a different machine. -### dotnet-sos +### dotnet-debugger-extensions -[dotnet-sos](dotnet-sos.md) installs the [SOS debugging extension](sos-debugging-extension.md) on Linux and macOS (and on Windows if you're using [Windbg/cdb](/windows-hardware/drivers/debugger/debugger-download-tools)). +[dotnet-debugger-extensions](dotnet-debugger-extensions.md) installs the [.NET debugger extensions](debugger-extensions.md) on Linux, macOS, and Windows. [LLDB](https://lldb.llvm.org/) is required for Linux and macOS, and [Windbg/cdb](/windows-hardware/drivers/debugger/debugger-download-tools) is needed for Windows. ## Other tools diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 91f27ebffda75..7a7ed0db9b00a 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -471,6 +471,8 @@ items: href: ../../core/diagnostics/dumps.md - name: Linux dumps href: ../../core/diagnostics/debug-linux-dumps.md + - name: .NET debugger extensions + href: ../../core/diagnostics/debugger-extensions.md - name: SOS debugger extension href: ../../core/diagnostics/sos-debugging-extension.md - name: Debug Windows dumps @@ -524,6 +526,8 @@ items: href: ../../core/diagnostics/dotnet-stack.md - name: dotnet-symbol href: ../../core/diagnostics/dotnet-symbol.md + - name: dotnet-debugger-extensions + href: ../../core/diagnostics/dotnet-debugger-extensions.md - name: dotnet-sos href: ../../core/diagnostics/dotnet-sos.md - name: dotnet-dsrouter