Skip to main content

Serialization

Complete guide to serializing .NET objects to TOON format using ToonSerializer.

Overview​

ToonSerializer (namespace ToonNet.Core.Serialization) is a static class that converts .NET objects to TOON format. Type metadata is discovered with reflection once per type and cached; property getters and setters are compiled accessors (typed delegates and expression trees), so later calls do not pay the reflection cost again.

Basic Serialization​

Serialize to String​

using ToonNet.Core.Serialization;

var person = new Person { Name = "Alice", Age = 30 };
string toon = ToonSerializer.Serialize(person);
// Name: Alice
// Age: 30

The output has no trailing newline.

Serialize to UTF-8​

When the text goes to the network, a file or a byte buffer, write UTF-8 directly. These overloads encode the serializer's pooled buffer straight to bytes, without creating an intermediate string; the bytes are exactly the UTF-8 of Serialize, without a byte order mark.

using System.Buffers;

byte[] utf8 = ToonSerializer.SerializeToUtf8Bytes(person);

// Any IBufferWriter<byte>: a PipeWriter, an ArrayBufferWriter<byte>, ...
var buffer = new ArrayBufferWriter<byte>();
ToonSerializer.Serialize(buffer, person);

// A stream, synchronously (it is left open)
ToonSerializer.Serialize(stream, person);

The value is serialized completely before anything is written, so a failure leaves the destination untouched.

Serialize to Stream​

using var stream = new MemoryStream();
await ToonSerializer.SerializeToStreamAsync(person, stream); // written as UTF-8

Serialize to File​

await ToonSerializer.SerializeToFileAsync(person, "person.toon"); // written as UTF-8

Serialization Options​

Using ToonSerializerOptions​

Configure serialization behavior with ToonSerializerOptions:

var options = new ToonSerializerOptions
{
PropertyNamingPolicy = PropertyNamingPolicy.CamelCase,
IgnoreNullValues = false
};

string toon = ToonSerializer.Serialize(person, options);

Indentation and Delimiter​

TOON output is always indented; nesting is expressed by indentation. The indent width and the delimiter used in inline arrays and tabular rows are set on the nested ToonOptions:

using ToonNet.Core;
using ToonNet.Core.Serialization;

var order = new Order { Tags = ["new", "priority"], Items = [new("A-1", 2), new("B-7", 1)] };

var options = new ToonSerializerOptions
{
ToonOptions = new ToonOptions
{
IndentSize = 4, // 1..100 (default 2)
Delimiter = '|' // ',' (default), '\t' or '|'
}
};

string toon = ToonSerializer.Serialize(order, options);
// Tags[2|]: new|priority
// Items[2|]{Sku|Qty}:
// A-1|2
// B-7|1

public class Order
{
public List<string> Tags { get; set; } = [];
public List<OrderLine> Items { get; set; } = [];
}

public record OrderLine(string Sku, int Qty);

Property Naming Policy​

Transform property names during serialization:

public enum PropertyNamingPolicy
{
Default, // Keep original names (default)
CamelCase, // firstName, lastName
SnakeCase, // first_name, last_name
LowerCase // firstname, lastname
}

Example:

var person = new Person
{
FirstName = "Alice",
LastName = "Smith",
Age = 30
};

// Default naming
var defaultOptions = new ToonSerializerOptions
{
PropertyNamingPolicy = PropertyNamingPolicy.Default
};
string toon1 = ToonSerializer.Serialize(person, defaultOptions);
// Output:
// FirstName: Alice
// LastName: Smith
// Age: 30

// CamelCase naming
var camelOptions = new ToonSerializerOptions
{
PropertyNamingPolicy = PropertyNamingPolicy.CamelCase
};
string toon2 = ToonSerializer.Serialize(person, camelOptions);
// Output:
// firstName: Alice
// lastName: Smith
// age: 30

// SnakeCase naming
var snakeOptions = new ToonSerializerOptions
{
PropertyNamingPolicy = PropertyNamingPolicy.SnakeCase
};
string toon3 = ToonSerializer.Serialize(person, snakeOptions);
// Output:
// first_name: Alice
// last_name: Smith
// age: 30

public class Person
{
public string FirstName { get; set; } = "";
public string LastName { get; set; } = "";
public int Age { get; set; }
}

Ignore Null Values​

Control null value serialization:

var user = new User
{
Username = "alice",
Bio = "Engineer",
Website = null
};

// Include nulls (default)
var includeNulls = new ToonSerializerOptions { IgnoreNullValues = false };
string toon1 = ToonSerializer.Serialize(user, includeNulls);
// Output:
// Username: alice
// Bio: Engineer
// Website: null

// Ignore nulls
var ignoreNulls = new ToonSerializerOptions { IgnoreNullValues = true };
string toon2 = ToonSerializer.Serialize(user, ignoreNulls);
// Output:
// Username: alice
// Bio: Engineer

public class User
{
public string Username { get; set; } = "";
public string? Bio { get; set; }
public string? Website { get; set; }
}

IgnoreNullValues only skips object properties; null items inside arrays are always kept.

Advanced Scenarios​

Serialize Collections​

// Array
int[] numbers = { 1, 2, 3, 4, 5 };
string toon1 = ToonSerializer.Serialize(numbers);
// [5]: 1,2,3,4,5

// List
List<string> names = new() { "Alice", "Bob", "Charlie" };
string toon2 = ToonSerializer.Serialize(names);
// [3]: Alice,Bob,Charlie

// Dictionary
Dictionary<string, int> scores = new()
{
["Math"] = 95,
["Physics"] = 87
};
string toon3 = ToonSerializer.Serialize(scores);
// Math: 95
// Physics: 87

// Uniform objects use the tabular form
var employees = new List<Employee>
{
new() { Name = "Alice", Department = "Engineering", Salary = 85000 },
new() { Name = "Bob", Department = "Marketing", Salary = 65000 }
};
string toon4 = ToonSerializer.Serialize(employees);
// [2]{Name,Department,Salary}:
// Alice,Engineering,85000
// Bob,Marketing,65000

// Uniform nested objects become nested field groups of the table (spec §9.3)
var orders = new[]
{
new { Id = 1, Customer = new { Name = "Ada", Country = "DK" }, Total = 99 },
new { Id = 2, Customer = new { Name = "Bob", Country = "UK" }, Total = 149 }
};
string toon5 = ToonSerializer.Serialize(orders);
// [2]{Id,Customer{Name,Country},Total}:
// 1,Ada,DK,99
// 2,Bob,UK,149

// A dictionary (or object) of at least two uniform objects is a keyed table (spec §9.5)
var servers = new Dictionary<string, Server>
{
["alpha"] = new() { Host = "a.example.com", Port = 8080 },
["beta"] = new() { Host = "b.example.com", Port = 9090 }
};
string toon6 = ToonSerializer.Serialize(new { Servers = servers });
// Servers[2:]{Host,Port}:
// alpha: a.example.com,8080
// beta: b.example.com,9090

// Empty collections
string toon7 = ToonSerializer.Serialize(new { Tags = new string[0] });
// Tags: []

Serialize with Custom Converters​

Register custom converters for specific types:

var options = new ToonSerializerOptions();
options.Converters.Add(new CustomDateTimeConverter()); // writes DateTime as yyyy-MM-dd HH:mm:ss

string toon = ToonSerializer.Serialize(obj, options);

CustomDateTimeConverter is the example of Custom Converters, which shows how to write one.

Serialize Polymorphic Types​

Shape shape = new Circle { Color = "Red", Radius = 5.0 };

// Declared as Shape: only Shape's properties are written
string toon = ToonSerializer.Serialize<Shape>(shape);
// Color: Red

// Declared as object: written as what it is, base-class properties first
string all = ToonSerializer.Serialize<object>(shape);
// Color: Red
// Radius: 5

public abstract class Shape
{
public string Color { get; set; } = "";
}

public class Circle : Shape
{
public double Radius { get; set; }
}

public class Rectangle : Shape
{
public double Width { get; set; }
public double Height { get; set; }
}

Since ToonNet 4.0, objects are written with the type they are declared as (the T of Serialize<T>, a property's type, a collection's item type, a dictionary's value type), as with System.Text.Json, so a derived type's members do not reach the output through a narrower type. A value declared as object is written with its runtime type. SerializeRuntimeTypes = true writes every object with its runtime type, as before 4.0; it also writes members of derived types that a base type was meant to hide (see Configuration). No type discriminator is written, so reading the text back into Shape needs a custom converter.

Serialize Complex Nested Structures​

var company = new Company
{
Name = "TechCorp",
Departments = new List<Department>
{
new Department
{
Name = "Engineering",
Employees = new List<Employee>
{
new Employee
{
Name = "Alice",
Position = "Senior Engineer",
Skills = new Dictionary<string, int>
{
["C#"] = 9,
["Python"] = 7
}
}
}
}
}
};

string toon = ToonSerializer.Serialize(company);

public class Company
{
public string Name { get; set; } = "";
public List<Department> Departments { get; set; }
}

public class Department
{
public string Name { get; set; } = "";
public List<Employee> Employees { get; set; }
}

public class Employee
{
public string Name { get; set; } = "";
public string Position { get; set; } = "";
public Dictionary<string, int> Skills { get; set; }
}

Output:

Name: TechCorp
Departments[1]:
- Name: Engineering
Employees[1]{Name,Position,Skills{"C#",Python}}:
Alice,Senior Engineer,9,7

The employees have the same shape, so they are written as a table; the Skills dictionary becomes a nested field group (Skills{"C#",Python}) whose values fill the last two cells of each row.

Async Serialization​

Serialize to String (Async)​

string toon = await ToonSerializer.SerializeAsync(data);

SerializeAsync runs synchronously and returns a completed ValueTask<string>; it exists for API symmetry.

Serialize to Stream (Async)​

await using var fileStream = File.Create("data.toon");
await ToonSerializer.SerializeToStreamAsync(data, fileStream);

Serialize to File (Async)​

await ToonSerializer.SerializeToFileAsync(data, "data.toon");

// With options
var options = new ToonSerializerOptions { PropertyNamingPolicy = PropertyNamingPolicy.CamelCase };
await ToonSerializer.SerializeToFileAsync(data, "data.toon", options);

Streaming Serialization (Large Datasets)​

For large datasets (database exports, ETL pipelines), write one document per item with SerializeDocumentsAsync instead of building one large string; items are pulled from the IAsyncEnumerable<T> one at a time:

await ToonSerializer.SerializeDocumentsAsync(dbContext.Users.AsAsyncEnumerable(), "users_export.toon");

await foreach (var user in ToonSerializer.DeserializeDocumentsAsync<User>("users_export.toon"))
{
await ProcessUserAsync(user!); // one document in memory at a time
}

Separator modes (blank line or ---), batch sizes, reading the array at a path item by item, and memory behavior are described in Streaming.

Performance Tips​

  1. Reuse ToonSerializerOptions: Create once, use multiple times
  2. Use async methods for I/O-bound operations
  3. Metadata is cached: the first call for a type builds and caches its metadata; later calls reuse it
  4. Stream large collections: use SerializeDocumentsAsync instead of building one huge string
  5. Write bytes directly: when the destination wants UTF-8, SerializeToUtf8Bytes or a buffer writer skips the string (on 10,000 records: 4–13% faster with a third of the allocation; a reused ArrayBufferWriter<byte> is 5–19% faster and makes writing flat tables almost allocation-free)
  6. Profile your code: Use BenchmarkDotNet for optimization
// Good: Reuse options
private static readonly ToonSerializerOptions _options = new()
{
PropertyNamingPolicy = PropertyNamingPolicy.CamelCase
};

public string SerializeUser(User user)
{
return ToonSerializer.Serialize(user, _options);
}

All Serialize Methods​

All methods take an optional ToonSerializerOptions? options = null; the async ones also take an optional CancellationToken.

MethodDescriptionUse Case
Serialize<T>(T value, options)Serialize to stringSimple, in-memory data
Serialize(object value, Type type, options)Serialize with a runtime typeNon-generic code
SerializeToUtf8Bytes<T>(T value, options)Serialize to UTF-8 bytesNetwork, caches, byte APIs
SerializeToUtf8Bytes(object value, Type type, options)Same, with a runtime typeNon-generic code
Serialize<T>(IBufferWriter<byte>, T value, options)Write UTF-8 to a buffer writer (also with a Type)Pipelines, pooled buffers
Serialize<T>(Stream, T value, options)Write UTF-8 to a stream synchronously (also with a Type)Synchronous I/O
Serialize<T>(T value, ToonTypeInfo<T>, options)Without reflection, through generated code (also SerializeToUtf8Bytes, buffer writer, stream, SerializeToStreamAsync)Trimming, NativeAOT
SerializeToValue<T>(T value, options)Convert to a ToonValue tree without textInspect or modify before encoding
SerializeToValue(object value, Type type, options)Same, with a runtime typeNon-generic code
SerializeAsync<T>(T value, options, ct)Serialize to string (ValueTask<string>)Async call sites
SerializeAsync<T>(Stream, T value, options, ct)Write UTF-8 to a stream (the stream first, as in System.Text.Json)Network, files
SerializeAsync(Stream, object value, Type type, options, ct)Same, with a runtime typeNon-generic code
SerializeToStreamAsync<T>(T value, Stream, options, ct)Write UTF-8 to a streamNetwork, files
SerializeToStreamAsync(Type, object value, Stream, options, ct)Same, with a runtime typeNon-generic code
SerializeToFileAsync<T>(T value, string filePath, options, ct)Write UTF-8 to a fileFile persistence
SerializeCollectionToFileAsync<T>(IEnumerable<T>, string filePath, options, ct)One document per item, blank-line separatedMulti-document files
SerializeDocumentsAsync<T>(IEnumerable<T>, Stream, options, ct)Same, to a streamMulti-document streams
SerializeDocumentsAsync<T>(IAsyncEnumerable<T>, string filePath, ...)Stream large datasets to a fileDB exports, large datasets
SerializeDocumentsAsync<T>(IAsyncEnumerable<T>, Stream, ...)Stream to a streamETL pipelines

The SerializeDocumentsAsync overloads that take ToonMultiDocumentWriteOptions control the separator mode and batch size. See Streaming for details.

Error Handling​

using ToonNet.Core;
using ToonNet.Core.Serialization;

try
{
string toon = ToonSerializer.Serialize(obj);
}
catch (ToonEncodingException ex)
{
// Circular reference or MaxDepth exceeded
Console.WriteLine($"Encoding error: {ex.Message}");
Console.WriteLine($"Property path: {ex.PropertyPath}"); // e.g. $.Children[0].Parent
}

ToonSerializationException is thrown by deserialization (type mismatches), not by Serialize. A [ToonConverter] type that does not implement IToonConverter throws InvalidOperationException.

Common Issues​

Issue: Circular References​

Problem: Object graph contains circular references.

Solution: Serialization throws ToonEncodingException. The reflection-based serializer detects the cycle and names the back-reference ("A circular reference was detected (property: $.Children[0].Parent)"). Generated code ([ToonSerializable] types, also through ToonSerializer) does not track the objects it writes: it reports the cycle when it exceeds MaxDepth ("Maximum depth of 100 exceeded during serialization (property: $.Next.Next...)"). Break the cycle:

using ToonNet.Core.Serialization.Attributes;

public class Parent
{
public string Name { get; set; } = "";
public List<Child> Children { get; set; } = [];
}

public class Child
{
public string Name { get; set; } = "";
// Don't serialize parent reference
[ToonIgnore]
public Parent? Parent { get; set; }
}

Issue: Large Objects​

Problem: Serializing very large objects causes memory issues.

Solution: Write directly to a file or stream, and for large collections stream the items:

await using var fileStream = File.Create("large-data.toon");
await ToonSerializer.SerializeToStreamAsync(largeObject, fileStream);

// Large collections: one document per item, never materialized as a whole
await ToonSerializer.SerializeDocumentsAsync(GetItemsAsync(), "items.toon");

SerializeToStreamAsync still holds the whole TOON text in memory before writing it (in pooled buffers, not a string, encoded to UTF-8 in chunks).

Thread-Safety​

ToonSerializer and a shared ToonEncoder are safe to use from several threads; see Configuration for the caches and options.

See Also​