ClrDump
Version: 1.0.2
Updated: 17.04.2006 (change log)
Introduction
ClrDump is a set of tools that allow to produce small minidumps of managed applications. In the past, it was necessary to use full dumps (very large in size) if you needed to perform post-mortem analysis of a .NET application. ClrDump can produce small minidumps that contain enough information to recover the call stacks of all threads in the application.
Use the following SOS commands to obtain the call stacks when debugging a crash dump produced with ClrDump:
.NET 1.1 applications:
- !dumpstack -EE
- Get managed call stack
- !dumpstack
- Get mixed managed/unmanaged call stack
- !clrstack
- Do not use it, it does not work correctly with small dumps and can destabilize your debugger
.NET 2.0 applications:
- !dumpstack -EE
- Get managed call stack
- !dumpstack
- Get mixed managed/unmanaged call stack
- !clrstack
- Get managed call stack
For .NET 1.1 applications, ClrDump uses undocumented interfaces implemented by .NET Runtime. For .NET 2.0 applications, it uses small minidump support in DbgHelp.dll.
Usage
ClrDump package consists of the following components:
- ClrDump.exe
- Command line tool that can be used to produce small minidumps of other processes
- ClrDump.dll
- Redistributable DLL that exposes a programmatic interface that allows to create minidumps with CLR state information
- ClrDump.h, ClrDump.lib
- Header and library files that allow to use ClrDump.dll's programmatic interface in C++ applications (managed applications can use ClrDump.dll's functions via P/Invoke)
ClrDump.exe supports the following command line parameters:
clrdump <pid> <dumpfile> [min | mid | max]
- pid
- Process id of the target process (required)
- dumpfile
- Name of the minidump file (required)
- min | mid | max
- Size of the minidump file (optional):
- min
- Smallest possible minidump (enough to recover call stacks of all threads); this option is used by default
- mid
- Very informative but still compressible minidump
- max
- Full minidump (full memory contents and all other kinds of information included; usually very large in size and not compressible)
Examples:
clrdump 128 c:\myapp.dmp clrdump 128 myapp.dmp mid
More information about the programmatic interface of ClrDump.dll can be found in API section below.
Supported platforms
Operating systems: Windows 2000, Windows XP, Windows Server 2003
.NET Runtimes: 1.1, 2.0
Download
Download ClrDump (489 Kb)
Redistributables
All executable components (ClrDump.exe and ClrDump.dll) are redistributable. You can use them in your applications for the purposes of debugging and crash reporting. DbgHelp.dll is required by the components in order to operate properly, and it is also redistributable (see redist.txt of Debugging Tools for Windows package).
Change log
- 17.04.2006 (version 1.0.2)
- New optional parameters for clrdump.exe: min, mid, max
- New API function: SetFilterOptions
- 26.02.2006 (version 1.0.1)
- First version
API
ClrDump.dll exposes the following functions:
BOOL __stdcall CreateDump ( DWORD ProcessId, LPCWSTR pFileName, DWORD DumpType, DWORD ExcThreadId, EXCEPTION_POINTERS* pExcPtrs ); |
Parameters:
|
Return value: TRUE if succeeded, FALSE if failed. If the function fails, GetLastError can be used to obtain the error code. |
Description: This function produces a minidump of the specified process (current or external, identified by process id). Optional exception information can be specified. Note: Creating a minidump of another process requires binding to the same version of .NET Runtime as loaded by the target process. Since binding cannot be undone after it has been performed, the current process cannot be used to create minidumps of processes that use different versions of .NET Runtime. A simple solution is to start a new process to create minidumps (e.g. use ClrDump.exe). |
BOOL __stdcall RegisterFilter ( LPCWSTR pFileName, DWORD DumpType ); |
Parameters:
|
Return value: TRUE if succeeded, FALSE if failed. If the function fails, GetLastError can be used to obtain the error code. |
Description: Registers a custom filter for unhandled exceptions in the current process (see SetUnhandledExceptionFilter function for more information about custom filters). If the process crashes with unhandled exception (it can be native or managed exception), the filter catches it and creates a minidump (with the specified file name). Note: Managed debugging can be affected. If the filter is registered and the application is running under managed-only debugger, the debugger will not receive notifications about unhandled exceptions in the application (by the nature of managed debugging architecture, which relies on its own custom filter for unhandled exceptions to notify the debugger). A typical solution is to register the custom filter (call RegisterFilter) only if you are not going to debug the application (for example, filter registration can be enabled/disabled via an application-specific configuration setting). |
BOOL __stdcall UnregisterFilter(); |
Return value: TRUE if succeeded, FALSE if failed. If the function fails, GetLastError can be used to obtain the error code. |
Description: Unregisters the custom filter for unhandled exceptions (registered with a call to RegisterFilter). |
DWORD __stdcall SetFilterOptions( DWORD Options ); |
Parameters:
|
Return value: The previously active options. |
Description: Sets or clears options that allow to configure various aspects of the custom filter's functionality. |
P/Invoke
Here are P/Invoke signatures that can be used to call ClrDump.dll's functions from managed applications:
[DllImport("clrdump.dll", CharSet = CharSet.Unicode, SetLastError=true)] static extern Int32 CreateDump( Int32 ProcessId, string FileName, Int32 DumpType, Int32 ExcThreadId, IntPtr ExtPtrs );
[DllImport("clrdump.dll", CharSet = CharSet.Unicode, SetLastError=true)] static extern Int32 RegisterFilter( string FileName, Int32 DumpType );
[DllImport("clrdump.dll", SetLastError=true)] static extern Int32 UnregisterFilter();
[DllImport("clrdump.dll")] static extern Int32 SetFilterOptions(Int32 Options); |