Quick Start

A five-minute tour of Memory.Introspect: configure logging, build a MemoryIntrospector, capture the current process's heap, and write the result to a .gcdump you can open in PerfView.

If you haven't installed the package yet, see Installation:

dotnet add package Memory.Introspect

1. Set up logging

The library logs through Microsoft.Extensions.Logging. Any provider works — the example below uses the console provider so you can watch the EventPipe handshake.

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(f => f.AddConsole());
var logger = loggerFactory.CreateLogger("Memory.Introspect");

If you don't pass a logger, the library writes to TextWriter.Null.

2. Build a `MemoryIntrospector`

MemoryIntrospector.Create takes a MemoryIntrospectorOptions and applies sensible defaults to anything you leave out.

using Memory.Introspect;

var introspector = MemoryIntrospector.Create(new()
{
    Logger = logger,
    Verbose = true,
});

A single MemoryIntrospector is reusable across calls; you don't need to create a new one per capture.

3. Collect the memory graph

CollectMemoryGraphAsync connects to the target process via EventPipe, triggers a GC, walks the heap, and returns a MemoryGraphResult.

using System.Diagnostics;

int pid = Process.GetCurrentProcess().Id;

var result = await introspector.CollectMemoryGraphAsync(pid);

if (!result.Success)
{
    logger.LogError("Failed to capture memory graph: {Exception}", result.Exception);
    return;
}

The first capture against a process pays a small fixed cost while EventPipe negotiates the session. Subsequent captures against the same process are noticeably faster.

4. Save the `.gcdump`

SaveToDisk writes the captured graph in the exact .gcdump format used by dotnet-gcdump, which means it opens cleanly in PerfView and Visual Studio.

var fileName = $"{DateTimeOffset.UtcNow:yyyy-MM-dd-HH-mm-ss}-process-{pid}.gcdump";
result.SaveToDisk(fileName);

logger.LogInformation("Wrote {File}", fileName);

Open the file in PerfView → Memory → Heap Snapshot to explore the heap.

5. Put it all together

app/Program.cs

using System.Diagnostics;
using Memory.Introspect;
using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(f => f.AddConsole());
var logger = loggerFactory.CreateLogger("Memory.Introspect");

int pid = Process.GetCurrentProcess().Id;

logger.LogInformation("Starting capture from process {Pid}", pid);

var introspector = MemoryIntrospector.Create(new()
{
    Logger = logger,
    Verbose = true,
});

var result = await introspector.CollectMemoryGraphAsync(pid);

if (result.Success)
{
    var file = $"{DateTimeOffset.UtcNow:yyyy-MM-dd-HH-mm-ss}-{pid}.gcdump";
    result.SaveToDisk(file);
    logger.LogInformation("Wrote {File}", file);
}
else
{
    logger.LogError(result.Exception, "Capture failed");
}

Where next?

Core Concepts

What EventPipe is, the difference between a .gcdump and a full process dump, and where this library fits in.

Guides

Memory graphs, full dumps, and sampling profiles — and which tool to open each one in.

Advanced

Configuration options, large-heap captures, and remote diagnostic ports.

Referenced by

Installation