---

---

1. What is dotnet-gcdump?

dotnet-gcdump is a lightweight .NET memory profiling tool that collects GC (Garbage Collector) heap dumps with minimal performance overhead.

It gives you:

• Managed heap snapshot
• Objects allocation information
• Object types, sizes, counts
• Reference trees (roots, retainers)
• Memory pressure analysis

It is part of the .NET diagnostics toolset along with:

• dotnet-counters
• dotnet-trace
• dotnet-dump
• dotnet-monitor

💡 Think of dotnet-gcdump as the “lightest way” to understand memory usage without pausing/stopping the app.

---

2. Why Use dotnet-gcdump?

✔ Extremely low overhead

You can capture memory dumps on live production apps with almost zero impact.

✔ Perfect for memory leak detection

It shows object types and counts to help identify:

• Memory leaks
• Excessive retained objects
• High fragmentation
• Objects not being freed

✔ Works cross-platform

Runs on Windows, Linux, and macOS.

✔ Great for comparing memory snapshots over time

Useful for before/after deployment analysis.

---

3. When to Use dotnet-gcdump?

Use it whenever you see:

🟡 Increasing memory usage in Production

• Memory slowly goes up → leak
• Too many pinned objects → fragmentation
• Large object heap (LOH) too high

🟡 GC performance issues

• High GC frequency
• High fragmentation
• Slowness or pauses

🟡 Investigate specific request memory spikes

Take a snapshot:

Before request → gcdump → After request

🟡 Compare two environment behaviors

• Prod vs Stage
• .NET version upgrade comparison
• New features memory comparison

---

4. How to Install dotnet-gcdump

dotnet tool install --global dotnet-gcdump
Code language: PHP (php)

Verify:

dotnet-gcdump --version

---

5. How to Use dotnet-gcdump

A. Find your running .NET process

dotnet-gcdump ps

Example output:

  5120   MyApp.Api
  5566   Orders.Web
  7788   BackgroundWorker
Code language: CSS (css)

---

B. Collect a GC dump from a running process

dotnet-gcdump collect --process-id 5566

You will get:

Writing gcdump to MyApp_20251125_142410.gcdump
Complete
Code language: CSS (css)

---

C. Collect a dump from a process that will start now

dotnet-gcdump collect -- myapp.exe
Code language: CSS (css)

---

D. Specify output file

dotnet-gcdump collect --process-id 5566 --output /tmp/myapp-leak.gcdump

---

6. How to Analyze a GCDump

✔ Best tool: PerfView

(Microsoft official memory analysis tool)

Open PerfView →
File → Open → .gcdump file

You will see:

You can inspect:

✔ Heap Size

✔ Object Types

✔ Count & Size

✔ Roots

✔ Retention Graph

✔ Diff View (compare two dumps)

---

7. Important Metrics in a GC Dump

Metric	Meaning	Why Important
Total Heap Size	Total memory used by managed heap	Detect memory bloat
Gen 0/1/2 Size	Memory per generation	Shows GC pressure
LOH (Large Object Heap)	Objects > 85 KB	High LOH = fragmentation risk
Pinned Objects	Objects fixed in memory	Affects GC performance
Object Count	How many objects of each type	Shows leaks (e.g., growing list)
Retainers / Roots	What is holding objects alive	Critical for leak detection
Diff View	Compare two snapshots	Identifies what grew

---

8. Common Memory Issues Detected via GCDump

🔥 Memory Leaks

• Singleton holding references
• Event handlers not unsubscribed
• Static lists growing

🔥 Large Object Heap Pressure

• Large arrays
• Images / byte[]
• Serialization buffers

🔥 Excessive Allocation

• Chatty LINQ
• Unoptimized JSON serialization
• Inefficient loops

🔥 Pinned Objects Issues

• GPU buffers
• Unsafe code
• Interop

---

9. Advanced Usage

A. Collect after forcing GC (for cleaner dump)

dotnet-gcdump collect --process-id 5566 --gc-collect

B. Collect for a process name (not PID)

dotnet-gcdump collect --name Orders.Api
Code language: CSS (css)

---

10. Advantages of dotnet-gcdump

Feature	Benefit
Lightweight	Safe in production
Zero-impact on performance	Unlike full dump
Easy to automate	CI, cron, scripts
Cross-platform	Works everywhere
Works with PerfView	Powerful analysis UI
Can compare snapshots	Detect leaks precisely

---

11. Limitations of dotnet-gcdump

Limitation	Notes
Cannot debug code execution	Use dotnet-trace
Only managed heap	No native memory
Limited call stacks	Not full session trace
No CPU profiling	Use dotnet-trace

---

12. Best Practices

⭐ Capture multiple dumps

Before, during, after load test.

⭐ Always analyze with PerfView

It is the official recommended tool.

⭐ Automate weekly GC dumps in production

Useful for long-running apps.

⭐ Combine with dotnet-counters

To monitor GC in real-time.

---

---

✅ 1. Basic Example — Capture a GC Dump from a Running Process

Step 1 — List running .NET processes

dotnet-gcdump ps

Example Output:

  5120   Orders.Api
  5566   LoginService
  7788   BackgroundWorker
Code language: CSS (css)

---

Step 2 — Capture a GC dump from PID 5120

dotnet-gcdump collect --process-id 5120

Output Example:

Writing gcdump to OrdersApi_20251125_141800.gcdump...
Complete
Code language: CSS (css)

👉 This creates a file like:

OrdersApi_20251125_141800.gcdump
Code language: CSS (css)

---

✅ 2. Example — Capture Dump of a Process by Name

If you don’t want to use PID:

dotnet-gcdump collect --name Orders.Api
Code language: CSS (css)

Output:

Found process 'Orders.Api' (PID 5120)
Writing gcdump...
Complete
Code language: JavaScript (javascript)

---

✅ 3. Example — Capture Dump and Save to Custom Path

dotnet-gcdump collect \
  --process-id 5566 \
  --output /logs/memory/Leak_5566_2PM.gcdump

---

✅ 4. Example — Collect After Forcing a Full GC

Useful when you want a clean snapshot:

dotnet-gcdump collect --process-id 5566 --gc-collect

Output:

Forcing full garbage collection...
Dumping managed heap...
Success

---

✅ 5. Example — Capture GCDump When Running a Command

Run your app and immediately collect:

dotnet-gcdump collect -- dotnet run --project MyApp.Api
Code language: CSS (css)

This starts MyApp.Api, collects dump, and exits.

---

✅ 6. Example — Compare Two GCDumps (using PerfView)

1. Take two dumps: dotnet-gcdump collect --process-id 5120 --output baseline.gcdump dotnet-gcdump collect --process-id 5120 --output after_load.gcdump
2. Open PerfView → Diff
3. Select both dumps → Analyze differences.

PerfView will show:

• Object growth
• Memory leaks
• Which objects increased or decreased

---

🚀 Real Production-like Examples

Example 7 — Detect Memory Leak in ASP.NET Core App

You see memory keeps increasing in production.
Take a gcdump:

dotnet-gcdump collect --process-id 44312 --output before_load.gcdump
Code language: CSS (css)

Run a heavy load test for 10 minutes…

Take second dump:

dotnet-gcdump collect --process-id 44312 --output after_load.gcdump
Code language: CSS (css)

Analyze diff:

• List<SessionObject> grew by +120,000 objects
• byte[] objects in LOH increased
• Some static dictionary retained references

Result → Memory leak confirmed.

---

Example 8 — Identify Large Object Heap (LOH) Pressure

App is slow. Using gcdump:

dotnet-gcdump collect --process-id 5566

PerfView shows:

• LOH: 600 MB
• Large arrays: byte[] of sizes 1 MB each
• Created during image resizing logic

Solution:
Switch to shared buffers, or pooling.

---

Example 9 — High Allocation Rate Investigation

dotnet-counters shows Allocation Rate 800 MB/sec.

Take gc-dump:

dotnet-gcdump collect --process-id 6632 --output high_alloc.gcdump
Code language: CSS (css)

PerfView:

• Huge number of JObject and JToken
• Caused by unoptimized JSON-parsing inside loop

---

🧪 Sample GCDump File Name Examples

Dump filenames generated automatically:

OrdersApi_20251125_091000.gcdump
PaymentService_20251125_152200.gcdump
BackgroundWorker_20251126_004500.gcdump
Code language: CSS (css)

---

📄 Sample dotnet-gcdump Output (Realistic)

Example console output when capturing:

PS> dotnet-gcdump collect --process-id 5566 --output api-memory-dump.gcdump

StartTime:       2025-11-25T14:15:03.123Z
Process Name:    Orders.Api
PID:             5566
GC Mode:         Server GC
Collecting...
Writing gcdump to 'api-memory-dump.gcdump'...
Complete
Dump Size:       85.32 MB
Code language: JavaScript (javascript)

---

🔍 Example PerfView Analysis (What You See)

Once opened in PerfView, you may see:

✔ Heap Summary

• Total Heap: 1.2 GB
• Gen 0: 120 MB
• Gen 1: 80 MB
• Gen 2: 350 MB
• LOH: 650 MB

✔ Top Object Types by Size

Type	Count	Size
byte[]	2,450	420 MB
JObject	50,000	200 MB
Dictionary<string, object>	8,000	130 MB
String	450,000	80 MB

✔ Retention Graph

You will see:

Static: SomeCache
 └── Dictionary<string, object>
       └── DataObject[]
             └── byte[]
Code language: CSS (css)

This tells you what is keeping objects alive → leak root.

---

🎯 Want me to generate a sample .gcdump file for training?

I can generate:

• Fake GC dump
• PerfView screenshots
• Step-by-step lab manual
• PPT (PowerPoint) 10–15 slides