Meziantou.Framework

Getting started

edit

Install the package

Add the Meziantou.Framework.HumanReadableSerializer package to your project:

dotnet package add Meziantou.Framework.HumanReadableSerializer

The examples of this documentation omit the using directives: they need using Meziantou.Framework.HumanReadable;. They check their results with assertions such as Assert.Equal, which show the text the serializer writes.

Serialize an object

HumanReadableSerializer.Serialize returns the text of any value:

var order = new
{
    Id = 42,
    Customer = new { Name = "Ada Lovelace", Email = "ada@example.com" },
    Lines = new[]
    {
        new { Product = "Keyboard", Quantity = 1 },
        new { Product = "Mouse", Quantity = 2 },
    },
    Notes = "Leave at the door\nRing twice",
};

var text = HumanReadableSerializer.Serialize(order);

Assert.Equal("""
    Id: 42
    Customer:
      Name: Ada Lovelace
      Email: ada@example.com
    Lines:
      - Product: Keyboard
        Quantity: 1
      - Product: Mouse
        Quantity: 2
    Notes:
      Leave at the door
      Ring twice
    """, text);
  • Each property is written on its own line as Name: value, in the order of the type's declaration.
  • A nested object is written below its property name, indented by two spaces.
  • Each item of a collection starts with - .
  • A string with several lines is written below its property name, one line per line.

Output format shows how each kind of value is written.

Pass options

HumanReadableSerializerOptions changes what is written, for instance to skip the null values:

var options = new HumanReadableSerializerOptions
{
    IncludeFields = true,
    DefaultIgnoreCondition = HumanReadableIgnoreCondition.WhenWritingNull,
};
var obj = new { Name = "John Doe", Nickname = (string?)null };
var output = HumanReadableSerializer.Serialize(obj, options);
Assert.Equal("Name: John Doe", output);

An options instance becomes read-only the first time it is used. Create it once, configure it, and reuse it: it caches what it learns about each type. See Options.

Next steps