TooString 0.8.8-preview

TooString is a Stringifier that goes places serializers don't.

TooString can

• make a best effort to stringify objects that JsonSerializer won't, including System.Reflection classes and System.Type; or for which JsonSerializer returns empty output, such as ValueTuples.
• Output as Json or C# object notation, or 'debug view' style, or [CallerArgumentExpression]

TooString offers 5 extension method groups on Object:

value.ToCSharpString()
value.ToJson();
value.ToSTJson()
value.TooString();
value.ToArgumentExpression();

TooString is not a serializer.

• TooString offers both maxDepth and maxEnumerableLength options for abbreviated output.
• TooString defaults to maxDepth = 3, maxEnumerableLength = 9.
• A serializer should be fail-fast: a Serializer should throw if it cannot deterministically serialize the input, but TooString will attempt to return a partial representation of the input if the input cannot be reliably serialized.

Default behaviour

• ToCSharpString() returns C# code creating anonymous objects, with Type names in comments.
• ToJson() returns JSON.
• ToSTJson() is a convenience method for System.Text.Json.JsonSerializer.Serialize(...).
• TooString() defaults to CSharp style; pass StringifyAs to choose an alternative output.
• ToArgumentExpression() returns the literal code expression.

Object output defaults to MaxDepth = 3, MaxEnumerableLength = 9, except for ToSTJson() which behaves identically to calling System.Text.Json.JsonSerializer.Serialize directly.

What's the different between ToJson() and ToSTJson()?

• System.Text.Json throws given unserializable types or values anywhere in the obkjecor if there are errors during serialization. ToJson() will catch errors and return what it's got.
• System.Text.Json will return "{}" by default for any ValueTuple. ToJson() will return the tuple items as an array.
• ToJson() can abbreviate output with both maxDepth and maxEnumerableLength options, System.Text.Json has no maxEnumerableLength option.
• System.Text.Json will return property values for classes in System.Numerics, ToJson() will represent multi-dimensional numbers as arrays.
• ToJson() has a whichProperties (default is BindingFlags.Instance | BindingFlags.Public) property to choose which members to stringify. STJ has an includeFields and IgnoreReadOnly... properties, and then offers TypeInfoResolvers.

Example:

var value = new { A = "boo", B = new Complex(3,4) };

value.ToCSharpString()  // Output is { A = "boo", B = <3; 4> } depending on .Net version.
value.ToJson();         // Output is reflection-based JSON: {"A":"boo","B":[3,4]}
value.ToSTJson();       // Output is System.Text.Json: {"A":"boo","B":{"Real":3,...}}

( Math.Sqrt(4 * Math.PI / 3)  ).ToArgumentExpression() 
// Output is the literal code: "Math.Sqrt(4 * Math.PI / 3)"

var tuple = (one: 1, two: "2", three: new Complex(3,4));

System.Text.Json.JsonSerializer.Serialize(tuple) // Output is "{}" because there  
                                                 // are no public properties on a tuple

tuple.ToJson()
// Output stringifies the tuple and the Complex number as arrays
// [1,"2",[3,4]] 

tuple.ToCSharpString()
// Output is created by reflection and 
// on Net6.0 : (1, "2", (3,4))  
// on Net8.0+: (1, "2", <3;4>)

var type = value.GetType();
System.Text.Json.JsonSerializer.Serialize(type) // Throws NotSupportedException
type.ToJson() // Outputs the type object, truncated to default MaxDepth = 3, MaxEnumerableLength = 9

Options

Options, and their default values, are:

 bool writeIndented = true,
 BindingFlags whichProperties = BindingFlags.Instance | BindingFlags.Public,
 int maxDepth = 3,
 int maxEnumerableLength = 9,
 string dateTimeFormat = "O",
 string dateOnlyFormat = "O",
 string timeOnlyFormat = "HH:mm:ss",
 string timeSpanFormat = "c"

maxEnumerableLength=0 means show zero elements. To show unlimited elements, use int.MaxValue

Options for ToSTJson() are the framework provided JsonSerializerOptions:

bool writeIndented = false,
 JsonNamingPolicy? propertyNamingPolicy = null,
 JsonIgnoreCondition defaultIgnoreCondition = JsonIgnoreCondition.Never,
 JsonNumberHandling numberHandling = JsonNumberHandling.Strict,
 ReferenceHandler? referenceHandler = null,
 bool propertyNameCaseInsensitive = false,
 bool includeFields = false,
 int maxDepth = 0,
 bool allowTrailingCommas = false,
 JsonCommentHandling readCommentHandling = JsonCommentHandling.Disallow,
 System.Text.Encodings.Web.JavaScriptEncoder? encoder = null

More Examples

// Reflection-based JSON
value.ToJson()
value.ToJson(writeIndented: true, maxDepth: 5)

// C# object notation
value.ToCSharpString()
value.ToCSharpString(writeIndented: true, maxDepth: 5)

// System.Text.Json
value.ToSTJson()
value.ToSTJson(writeIndented: true, propertyNamingPolicy: JsonNamingPolicy.CamelCase)

// TooString with style selection
value.TooString()
value.TooString(StringifyAs.Json)
value.TooString(maxDepth: 4, maxEnumerableLength: 9, style: StringifyAs.CSharp)
value.TooString(TooStringOptions.ForCSharp with { MaxEnumerableLength = 1 })
value.TooString(TooStringOptions.ForJson with { MaxEnumerableLength = 2 })

Gotchas

Example: Json-serializing value tuples is something of a surprise because (unlike anonymous objects or records or structs) they have no public properties and their public fields are not named as per your code. Takeaway: don't choose value tuples for public apis that must be jsonned.

System.Text.Json.JsonSerializer.Serialize(  (one:1, two:"2")  )
// Output is "{}" because there are no public fields

(one:1, two:"2").ToSTJson()
// Output is "{}"

(one:1, two:"2").ToJson()
// Output is [1,"2"].

ChangeLog

<pre> ChangeLog

0.8.x Simplify to: ToCSharpString(), ToJson(), ToSTJson(), TooString(), ToArgumentExpression(). Offer individual parameters in preference to a TooStringOptions object. Rename StringifyAs.___ members CSharp output includes Type in comments, e.g. : new /TypeName/ { ... } 0.7.0 Easier to build new TooStringOptions(){...}. Sanitize overloads. 0.6.0 TooString() defaults to CSharp. 0.5.0 ReflectionOptions.With(...), TooStringOptions.With(...). Fixes. 0.4.0 ReflectionOptions.MaxLength default = 9 ReflectionOptions.ForJson and ReflectionOptions.ForDebugView instead of Default. More overloads. 0.3.0 ReflectionOptions.MaxLength limits display of enumerable elements 0.2.0 Added Net8 (NB Net8 Json and Numerics output is different from Net6) Rename StringifyAs to TooStringHow. Fix SerializationStyle.Reflection output of DateTime, DateOnly, TimeOnly. 0.1.0 Can use DebugView, Json, ToString() or [CallerArgumentExpression] and can output Json or Debug strings. </pre>