Debugging Attributes and Visualizing Types
Objective
The System.Diagnostics attributes change what a debugger shows and which
frames it steps into, and one of them, [StackTraceHidden], changes the text of
every exception that crosses your code. A test project cannot drive a debugger,
so this concept measures what a program can observe: the attributes read with
CustomAttributeData, the BCL's own List<T> proxy, how StackTrace, Exception.StackTrace and Environment.StackTrace
react to each attribute, what Debugger, Debug.Assert and Trace do with no
debugger attached, and whether dotnet-dump analyze honors any of it. What the
Visual Studio, Rider or VS Code windows do is "docs only": no IDE ran here.
Versions: .NET SDK 10.0.100, runtime 10.0.0, TFM net10.0, dotnet-dump
10.0.750501, macOS arm64 (Apple M4 Max).
Use Cases
- Make
Customer { First, Last, Orders }read asAna Silva (2 orders)in a watch window instead of{Customer}. - Show a custom collection as its items, not its internals.
Deep Dive
The attributes, read from metadata
They read like any other attribute (see
attributes and
reflection). Their
AttributeUsage, measured:
textDebuggerDisplayAttribute Assembly, Class, Struct, Enum, Property, Field, Delegate multiple=True inherited=True DebuggerBrowsableAttribute Property, Field multiple=False inherited=True DebuggerTypeProxyAttribute Assembly, Class, Struct multiple=True inherited=True DebuggerStepThroughAttribute Class, Struct, Constructor, Method multiple=False inherited=False DebuggerHiddenAttribute Constructor, Method, Property multiple=False inherited=False DebuggerNonUserCodeAttribute Class, Struct, Constructor, Method, Property multiple=False inherited=False StackTraceHiddenAttribute Class, Struct, Constructor, Method multiple=False inherited=False
DebuggerHidden is the only step attribute not allowed on a type, and none of
the step attributes nor StackTraceHidden is inherited.
DebuggerDisplay: a string, not code
csharp[assembly: DebuggerDisplay("Money {Amount} {Currency,nq}", Target = typeof(Money))]
[DebuggerDisplay("{Name,nq} x{Qty}", Name = "line", Type = "OrderLine")]
public class OrderLine { public string Name { get; set; } = ""; public int Qty { get; set; } }
[DebuggerDisplay("{DebuggerDisplay,nq}")] // the pattern from the docs
public class Customer
{
public string First { get; set; } = ""; public string Last { get; set; } = "";
public List<string> Orders { get; } = new();
private string DebuggerDisplay => $"{First} {Last} ({Orders.Count} orders)";
}
[DebuggerDisplay("{Missing} and {Count - 2} and {Next()}")]
public class Dubious { public int Count = 8; public int Calls; public int Next() => ++Calls; }GetCustomAttributesData() returns the text as written, the assembly-level
form (for a type you do not own) included:
text[DebuggerDisplayAttribute("{Name,nq} x{Qty}", Name = "line", Type = "OrderLine")] [DebuggerDisplayAttribute("Money {Amount} {Currency,nq}", Target = typeof(Lab.Money))] Dubious.Calls after reading its attribute "{Missing} and {Count - 2} and {Next()}": 0
Measured: the compiler does not parse the string ({Missing} names no member
and the build had 0 warnings, 0 errors); reading the attribute never evaluates
{Next()}; and the attribute stays in a Release assembly. Braces hold member
names as text, so a rename does not update them, but a constant interpolated
string keeps them in sync (same metadata as the hand-written one):
csharp[DebuggerDisplay($"{{{nameof(Name)},nq}} x{{{nameof(Qty)}}}")] // -> "{Name,nq} x{Qty}"Docs only, from the Visual Studio page: text in braces is evaluated as a field,
property or method; ,nq removes the quotes; Name and Type change those
columns; DebuggerDisplay wins over an overridden ToString(); evaluating
expressions is "the most expensive operation in the debugger", happens on each
display and can change application state; and the "Show raw structure of
objects" option ignores the attribute. The tool you use to look at an object
runs your code, so {Next()} is the case to avoid.
DebuggerBrowsable and DebuggerTypeProxy
[DebuggerBrowsable(state)] takes Never (hide), Collapsed or RootHidden
(show the elements, not the value). Read back from a class that sets all three,
plus an auto-property:
textField Secret Never Field Flat RootHidden Field Folded Collapsed Field <Plain>k__BackingField Never <- Debug build Field <Plain>k__BackingField <- Release build, no attribute
The last two lines were the only difference between the Debug and Release
outputs: the compiler adds DebuggerBrowsable(Never) to an auto-property's
backing field only in Debug (SDK 10.0.100, one property).
[DebuggerTypeProxy(typeof(P))] replaces the type's expansion with the public
members of P, whose constructor takes the target. The BCL does this for
List<T>; this program read that attribute, built the proxy by reflection and
read its properties:
textList`1: [DebuggerTypeProxyAttribute(typeof(System.Collections.Generic.ICollectionDebugView`1))] [DebuggerDisplayAttribute("Count = {Count}")] proxy ICollectionDebugView`1 (public=False): Items : Int32[] RootHidden value=[10, 20, 30]
The dotnet/runtime source matches (T[] Items with RootHidden, copied on
each read). The same pattern for your own collection:
csharp[DebuggerTypeProxy(typeof(BagDebugView<>))][DebuggerDisplay("Count = {Count}")]
public class Bag<T> : IEnumerable<T> { /* ... */ }
public sealed class BagDebugView<T>(Bag<T> bag) // reflection read Items as String[] [x, y]
{
[DebuggerBrowsable(DebuggerBrowsableState.RootHidden)] public T[] Items => bag.ToArray();
}Docs only: the debugger builds a proxy "every time it needs to display a
variable", so keep the constructor cheap; only public members show; a C# target
must be an open generic (Bag<>).
Frames: step, hide and non-user code
[DebuggerStepThrough], [DebuggerHidden] and [DebuggerNonUserCode] are
instructions to a stepping debugger (docs only). What a program sees is that none
of them changes an exception. One chain, throwing in Thrower, with one
attribute on the middle method (Debug and Release identical with NoInlining;
inlining was not varied):
textattribute on the middle frame ex.StackTrace new StackTrace(ex).FrameCount frames in the object (none) 4 lines 4 Thrower > Plain > lambda > Case [StackTraceHidden] 3 lines 4 Thrower > HiddenTrace > lambda > Case [DebuggerHidden], [DebuggerStepThrough], [DebuggerNonUserCode]: each 4 lines, 4 frames, same as none
Only [StackTraceHidden] (.NET 6) edits the text, and the frame is still in
GetFrames(), so code that walks frames sees a stack the text does not show. Two
more placements. On the method that throws, the throw line disappears and the
top frame is the caller, at Lab.Stacks.Plain(Action a) ... line 11 (FrameCount
4, 3 lines). On a static class Guard, its NotNull vanished and the first
line was the caller of Guard.NotNull(null) (FrameCount 3, 2 lines).
Environment.StackTrace follows the same rule. From inside a method called
through a hidden one:
textnew StackTrace().FrameCount = 4 (Inside > HiddenTrace > Run > Main) StackTrace.ToString(): Inside, Run, Main Environment.StackTrace: get_StackTrace, Inside, Run, Main
The BCL is a heavy user. Declared members of System.Private.CoreLib 10.0.0, by reflection: DebuggerHidden on 342 members, DebuggerStepThrough on
63 members and 6 types, StackTraceHidden on 49 members and 7 types,
DebuggerDisplay on 56 types, DebuggerTypeProxy on 38, DebuggerVisualizer
on none. It does not hide every throw helper: ThrowIfNull(null) still showed
at System.ArgumentNullException.Throw(String paramName). Use it on your own
helpers when the frame would only distract (see
guard clauses and
exceptions).
Debugger, Debug.Assert and Trace without a debugger
Plain processes, no debugger anywhere, exit codes from $?:
textDebug build Release build IsAttached, then Launch() False; Launch() returned True, IsAttached still False same Debugger.Break() continued, exit 0 same Debug.Assert(false, "msg") "Process terminated. Assertion failed.", exit 134 call removed, exit 0 Trace.Assert(false, "msg") "Process terminated. Assertion Failed", exit 134 same, exit 134 Debug/Trace.WriteLine nothing on the console (only DefaultTraceListener) + ConsoleTraceListener both lines only the Trace line
Three surprises. Debugger.Launch() returned True while IsAttached stayed
False: nothing was launched on macOS (Windows behavior is docs only). Debugger.Break() is a no-op
without a debugger and is not [Conditional], so a forgotten one ships. And
Trace.Assert kills a Release process: reflection confirms Debug.Assert and
Debug.WriteLine carry Conditional("DEBUG"), Trace.Assert and
Trace.WriteLine carry Conditional("TRACE"), and TRACE is defined in
Release (see
preprocessor directives).
An invariant that must never stop production is a Debug.Assert.
dotnet-dump does not apply them
Does dotnet-dump analyze show a display string or a proxy? I ran a Release
build holding an OrderLine, a Customer, a Bag<string>, a Money and a
List<int>, took dotnet-dump collect --type Heap (354 MB, from a private
runtime copy with createdump made executable, as in the
dotnet-trace, dump and gcdump
concept) and ran dumpobj on each. The output is the raw object, e.g. for Lab.Customer
three fields named <First>k__BackingField, <Last>k__BackingField and
<Orders>k__BackingField with addresses as values.
No Ana Silva (2 orders) and no Count = 2; a List<string> showed _items and
_size 2, and help has no command about display strings or proxies.
[DebuggerVisualizer] names a separate assembly that a debugger loads to draw a
value in its own window: docs only (see the Visual Studio page on custom
visualizers).
Book vs today
Older .NET books present DebuggerDisplay, Debug.Assert and Debug.WriteLine
as the diagnostics toolkit. The display and proxy attributes are unchanged and
still worth three lines for a type you inspect daily. What moved: Debug.WriteLine printed nothing here without a listener,
where ILogger, OpenTelemetry and EventPipe are what production reads (see
structured logging);
a failing assert ends this runtime's process (exit 134); [StackTraceHidden] is
new since .NET 6, so older material has no way to shorten an exception text;
and post-mortem work goes through dotnet-dump, where the display attributes
are not used (measured above; the IDE's dump window was not run).
Trade-offs
- The display string is unchecked text that can run your code.
{Missing}built with 0 warnings, and{Next()}is a call on every refresh. Usenameofas above and keep the logic in a private property with no side effects. - A proxy copies.
ItemscallsToArray()on each expansion: costly for a lazy or huge sequence. Cap it. [StackTraceHidden]removes evidence. On a throwing method the text named its caller. Reserve it for tiny helpers and keep logging the full exception.Trace.Assertand a forgottenDebugger.Break()ship. The first ended a Release process (exit 134); the second is a no-op until a debugger attaches.
Documentation Links
- Display custom info using DebuggerDisplay, Visual Studio, Microsoft Learn
- Use the DebuggerTypeProxy attribute, Visual Studio, Microsoft Learn
- Enhancing debugging with the debugger display attributes, Microsoft Learn
- Create custom visualizers of data, Visual Studio, Microsoft Learn
- StackTraceHiddenAttribute class, Microsoft Learn
- ICollectionDebugView.cs, dotnet/runtime, GitHub
- dotnet-dump, Microsoft Learn