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
- Reuse ToonSerializerOptions: Create once, use multiple times
- Use async methods for I/O-bound operations
- Metadata is cached: the first call for a type builds and caches its metadata; later calls reuse it
- Stream large collections: use
SerializeDocumentsAsyncinstead of building one huge string - Write bytes directly: when the destination wants UTF-8,
SerializeToUtf8Bytesor a buffer writer skips the string (on 10,000 records: 4–13% faster with a third of the allocation; a reusedArrayBufferWriter<byte>is 5–19% faster and makes writing flat tables almost allocation-free) - 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.
| Method | Description | Use Case |
|---|---|---|
Serialize<T>(T value, options) | Serialize to string | Simple, in-memory data |
Serialize(object value, Type type, options) | Serialize with a runtime type | Non-generic code |
SerializeToUtf8Bytes<T>(T value, options) | Serialize to UTF-8 bytes | Network, caches, byte APIs |
SerializeToUtf8Bytes(object value, Type type, options) | Same, with a runtime type | Non-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 text | Inspect or modify before encoding |
SerializeToValue(object value, Type type, options) | Same, with a runtime type | Non-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 type | Non-generic code |
SerializeToStreamAsync<T>(T value, Stream, options, ct) | Write UTF-8 to a stream | Network, files |
SerializeToStreamAsync(Type, object value, Stream, options, ct) | Same, with a runtime type | Non-generic code |
SerializeToFileAsync<T>(T value, string filePath, options, ct) | Write UTF-8 to a file | File persistence |
SerializeCollectionToFileAsync<T>(IEnumerable<T>, string filePath, options, ct) | One document per item, blank-line separated | Multi-document files |
SerializeDocumentsAsync<T>(IEnumerable<T>, Stream, options, ct) | Same, to a stream | Multi-document streams |
SerializeDocumentsAsync<T>(IAsyncEnumerable<T>, string filePath, ...) | Stream large datasets to a file | DB exports, large datasets |
SerializeDocumentsAsync<T>(IAsyncEnumerable<T>, Stream, ...) | Stream to a stream | ETL 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
- Deserialization: Convert TOON back to objects
- Configuration: Detailed options guide
- Performance Tuning: Optimization strategies
- Custom Converters: Create custom type converters