What are WeakReference and ConditionalWeakTable in .NET, and when are weak references the right tool?

1. How weak references work in the runtime

new WeakReference<T>(obj) allocates a small managed object that owns a GC handle of type weak short (or weak long with trackResurrection). During a GC:

1. Marking runs from strong roots only; weak handles are not roots.
2. After marking, the GC scans weak short handles: if the target wasn't marked, the handle is set to null.
3. Finalisable unmarked objects are moved to the f-reachable queue (they become reachable again).
4. The GC scans weak long handles: if the target is still unmarked, null it; if it was resurrected by finalisation, keep it.
5. If the target survives and moves, the handle is updated to the new address.

strong roots --> A --> B         weak handle ---> C   (C unmarked)
                                    after GC: handle = null, C reclaimed

2. Dependent handles: how ConditionalWeakTable avoids cycles

A dependent handle says: "keep secondary alive only while primary is alive", without making primary reachable from it. ConditionalWeakTable stores each entry as a dependent handle (key = primary, value = secondary).

key (primary) --dependent--> value (secondary)
value --> key        // even this back-reference doesn't keep the key alive

With a normal dictionary, table -> value -> key would root the key forever. With a dependent handle, the GC marks the value only if the key is already marked through some other path.

3. ConditionalWeakTable API

Keys are compared by reference identity, so two equal records are different keys.

4. Short vs long in practice

Long weak references let you observe objects in a "finalised but not yet reclaimed" state, which is rarely what you want.

5. Observing handle usage

• dotnet-dump analyze → gchandles -stat shows counts by handle type (Strong, Pinned, WeakShort, WeakLong, Dependent).
• A steadily rising WeakShort or Dependent count suggests weak references or ConditionalWeakTable entries are created per request.
• PerfView GC events include handle counts per GC on verbose traces.

6. Patterns and anti-patterns

7. Version notes

8. Try it yourself

1. Run the code example: the dictionary keeps the rule alive, ConditionalWeakTable doesn't.
2. Make the value hold a reference back to the key and confirm ConditionalWeakTable still allows collection while a Dictionary doesn't.
3. Create 1 million WeakReference<object> instances and compare GC.GetTotalPauseDuration() with and without them across a few induced GCs.
4. Build a weak cache with WeakReference<byte[]> for 10 KB arrays under allocation load and measure the hit rate.
5. Write a test that proves an object subscribed to a static event is leaked, then fix it with unsubscription and watch the test pass.
6. Take a dump and run gchandles -stat.

using System.Runtime.CompilerServices;

var strongMap = new Dictionary<Rule, string>();
var weakMap = new ConditionalWeakTable<Rule, string>();

WeakReference<Rule> viaDictionary = Attach(strongMap, weakMap, useWeak: false);
WeakReference<Rule> viaWeakTable = Attach(strongMap, weakMap, useWeak: true);

GC.Collect();
GC.WaitForPendingFinalizers();
GC.Collect();

Console.WriteLine($"Rule kept alive by Dictionary: {viaDictionary.TryGetTarget(out _)}");          // True: leak
Console.WriteLine($"Rule kept alive by ConditionalWeakTable: {viaWeakTable.TryGetTarget(out _)}"); // False

// Correct use of WeakReference<T>: copy the target to a local
var cacheEntry = new WeakReference<byte[]>(new byte[1024]);
if (cacheEntry.TryGetTarget(out byte[]? data))
    Console.WriteLine($"Still cached: {data.Length} bytes");
else
    Console.WriteLine("Collected; recompute");

[MethodImpl(MethodImplOptions.NoInlining)]
static WeakReference<Rule> Attach(Dictionary<Rule, string> strong, ConditionalWeakTable<Rule, string> weak, bool useWeak)
{
    var rule = new Rule($"rule-{useWeak}");
    if (useWeak) weak.Add(rule, "compiled form");
    else strong[rule] = "compiled form";
    return new WeakReference<Rule>(rule);
}

sealed record Rule(string Name);