ClrMdPack API

Drew Marsh edited this page May 16, 2013 · 5 revisions

ClrMdPack API

The root of functionality in ScriptCs.ClrMD is the ClrMdPack class. Through this class you will do things like attach and detach from processes, access details of the currently running and execute the command ScriptCs.ClrMd commands (such as the DumpXXX commands).

Properties

bool IsAttached { get; }

True if currently attached to a process, otherwise false.

Process AttachedProcess { get; }

Returns the System.Diagnostics.Process currently attached process or null if not currently attached.

ClrRuntime ClrRuntime { get; }

Returns a ClrMD Microsoft.Diagnostics.Runtime.ClrRuntime instance for the currently attached process or null if not currently attached.

Attaching

The first step to diagnosing is attaching to a process. There are a few overloads of the Attach method provided for convenience. Once attached the execution of the target process is immediately paused for inspection.

All overloads return you a ClrMD ClrRuntime instance that you can use for direct access to the ClrMD API if you desire. Note that you can always get the current ClrRuntime instance from the ClrMdPack::ClrRuntime property as well.

ClrRuntime Attach(string processName, int attachWaitTimeMilliseconds = 5000)

Attaches to a currently running process using the process' executable name specified by processName. You can optionally pass a wait time in milliseconds via attachWaitTimeMilliseconds that indicates how long ClrMD should wait to be able to attach to the target process.

var clrmd = Require<ClrMdPack>();
var clrt = clrmd.Attach("MyApplication");

Note: The processName should not include the ".exe" extension.

ClrRuntime Attach(int processId, int attachWaitTimeMilliseconds = 5000)

Attached to a currently running process using the operating system's PID for the process. This overload must be used when attaching to a process which has multiple instances running. You can optionally pass a wait time in milliseconds via attachWaitTimeMilliseconds that indicates how long ClrMD should wait to be able to attach to the target process.

var clrmd = Require<ClrMdPack>();
var clrt = clrmd.Attach(1234);

Detatching

Once attached to a process, in order to allow it to resume execution you must detatch.

ScriptCs.ClrMD will automatically detatch when the ScriptCs environment terminates the script pack. So if, for example, you're using REPL and you forget to call Detatch before exiting, it will automatically take care of this for you so you don't leave the target process frozen.

ClrRuntime Detach()

Detaches from the currently attached process.

clrmd.Detach();