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:

ProcessId
Process id of the target process (use GetCurrentProcessId function or its .NET equivalent if you want to create a minidump of the current process)
pFileName
Name of the minidump file
DumpType
Kinds of information that should be included into the minidump, represented by a set of MiniDump* flags (members of MINIDUMP_TYPE enumeration). You can find more information about MiniDump* flags in this article. In most cases, the value of zero (equivalent of MiniDumpNormal flag) is sufficient.
ExcThreadId
Thread id of the thread that generated the exception. Required only if pExcPtrs parameter is not null, otherwise ignored.
pExcPtrs
Pointer to EXCEPTION_POINTERS structure that describes the current exception. This parameter is required only if you call CreateDump from an exception filter, otherwise it can be null. Note that if you are interested only in managed functions on the call stack, this parameter can be set to null.

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:

pFileName
Name of the minidump file
DumpType
Kinds of information that should be included into the minidump, represented by a set of MiniDump* flags (members of MINIDUMP_TYPE enumeration). You can find more information about MiniDump* flags in this article. In most cases, the value of zero (equivalent of MiniDumpNormal flag) is sufficient.

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:

Options
Filter options (combination of flags that specify whether the particular option should be turned on or off)
The following options are currently supported:
CLRDMP_OPT_CALLDEFAULTHANDLER (0x1)
After creating the minidump, pass control to the default (system-provided) exception handler. The default handler will report the error to the user (using the standard Windows Error Reporting dialog) and/or launch the registered just-in-time debugger. This option is turned off by default.

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