Dumpify Documentation

Dumpify is a debugging and visualization tool for .NET console applications. Its features are categorized into three main areas:

Display Features

• Labels: Add descriptive headers to output.
• Table Formatting: Configure borders, headers, and alignment.
• Color Themes: Customize colors for all value types.
• Type Names: Control how type names are displayed.

Data Control

• Member Filtering: Control which properties, fields, or private members are displayed.
• Circular References: Safe handling of recursive/circular object structures.
• Collections: Specialized rendering for arrays, lists, and dictionaries.
• Depth Limiting: Prevent excessive nesting in complex objects.

Extensibility

• Custom Type Handlers: Define custom rendering logic for specific types.
• Output Targets: Support for Console, Debug, Trace, or custom outputs.
• Custom Renderers: Ability to implement your own rendering engine.

Dumpify prevents infinite loops and stack overflows by tracking object references during rendering. When the engine encounters an object instance it has already visited in the current graph, it displays a reference indicator instead of recursing.

Key technical behaviors:

• Reference Tracking: Detection is based on object identity (reference equality), not value equality. Two different objects with identical property values are rendered fully. The same object instance appearing multiple times is detected as a cycle.
• Value Types: Value types cannot cause circular references as they are copied.
• Scenarios Supported: Self-references, parent-child relationships, linked lists, graph structures, and Entity Framework navigation properties.

// Not circular - different instances with same values
var a = new Point { X = 1, Y = 2 };
var b = new Point { X = 1, Y = 2 };
new[] { a, b }.Dump();  // Both rendered fully

// Circular - same instance
var c = new Node { Value = 1 };
new[] { c, c }.Dump();  // Second reference detected

The TruncationMode enum determines how collections are displayed when they exceed the MaxCollectionCount limit. You can set this globally for all dumps or override it on a per-call basis.

Available Modes

• Head: Shows the first $N$ elements and truncates the rest at the end.
• Tail: Shows the last $N$ elements and truncates the beginning.
• HeadAndTail: Shows the first $N/2$ elements and the last $N/2$ elements, with a truncation marker in the middle.

Best Practices

• Use Head for ordered data, logs, or time-series where the start is most important.
• Use Tail for logs or queues where the most recent items are at the end.
• Use HeadAndTail to get a sense of both the start and end of a collection simultaneously.

// Global configuration
DumpConfig.Default.TruncationConfig.Mode = TruncationMode.HeadAndTail;
DumpConfig.Default.TruncationConfig.MaxCollectionCount = 10;

// Per-call override
var truncationConfig = new TruncationConfig
{
    Mode = TruncationMode.Tail,
    MaxCollectionCount = 5
};
myLargeList.Dump(truncationConfig: truncationConfig);

The MemberFilterContext struct provides the necessary context to decide whether a specific member (property or field) should be included in the output during rendering. It is used within filter functions configured via DumpConfig.Default.MembersConfig.MemberFilter (for global configuration) or the memberFilter parameter on individual Dump method calls (for per-call configuration).

Properties

• Member (IValueProvider): The member being filtered. Use this to access metadata like Name, MemberType, or reflection Info.
• Value (object?): The actual value of the member. Note: This is lazily evaluated and only accessed when you call the property. Avoid accessing this if your filter logic can be satisfied by metadata alone to improve performance.
• Source (object): The parent object containing the member.
• Depth (int): The current rendering depth (where 0 is the root object).

// Global configuration
DumpConfig.Default.MembersConfig.MemberFilter = ctx => ctx.Value is not null;

// Per-call configuration
myObject.Dump(memberFilter: ctx => ctx.Depth < 2);

Dumpify provides several built-in methods to direct your object dumps to different destinations depending on your environment and use case:

• Dump(): Uses the globally configured default (usually Console).
• DumpConsole(): Always outputs to Console.WriteLine (ideal for terminal apps).
• DumpDebug(): Outputs to System.Diagnostics.Debug (ideal for IDE debug windows like Visual Studio or VS Code).
• DumpTrace(): Outputs to System.Diagnostics.Trace (ideal for trace listeners and logging frameworks).
• DumpText(): Returns the formatted output as a string instead of writing it (ideal for logging, file output, or unit testing).

// Examples of different targets
myObject.Dump();          // Default
myObject.DumpConsole();   // Terminal
myObject.DumpDebug();     // IDE Debugger
myObject.DumpTrace();     // Trace Listeners
string text = myObject.DumpText(); // Capture as string