Basic Serialization
Learn the fundamentals of TOON serialization with practical examples. The samples need using ToonNet.Core.Serialization;
(and using ToonNet.Core; for the exception types); put the types they declare after the statements, or in their own
files.
Primitive Types
Strings
string text = "Hello, ToonNet!";
string toon = ToonSerializer.Serialize(text);
// Output: "Hello, ToonNet!"
// (quoted because it contains the delimiter ','; plain strings like Hello World are written unquoted)
string? restored = ToonSerializer.Deserialize<string>(toon);
Numbers
int number = 42;
string toon = ToonSerializer.Serialize(number);
// Output: 42
double price = 19.99;
string toonPrice = ToonSerializer.Serialize(price);
// Output: 19.99
Booleans
bool isActive = true;
string toon = ToonSerializer.Serialize(isActive);
// Output: true
bool restored = ToonSerializer.Deserialize<bool>("false");
Null Values
string? nullValue = null;
string toon = ToonSerializer.Serialize(nullValue);
// Output: null
string? restored = ToonSerializer.Deserialize<string?>("null");
Collections
Arrays
int[] numbers = { 1, 2, 3, 4, 5 };
string toon = ToonSerializer.Serialize(numbers);
Output:
[5]: 1,2,3,4,5
Lists
List<string> fruits = new() { "Apple", "Banana", "Cherry" };
string toon = ToonSerializer.Serialize(fruits);
Output:
[3]: Apple,Banana,Cherry
Dictionaries
Dictionary<string, int> scores = new()
{
["Alice"] = 95,
["Bob"] = 87,
["Charlie"] = 92
};
string toon = ToonSerializer.Serialize(scores);
Output:
Alice: 95
Bob: 87
Charlie: 92
Complex Objects
Simple Object
var product = new Product
{
Name = "Laptop",
Price = 999.99m,
InStock = true
};
string toon = ToonSerializer.Serialize(product);
public class Product
{
public string Name { get; set; } = "";
public decimal Price { get; set; }
public bool InStock { get; set; }
}
Output:
Name: Laptop
Price: 999.99
InStock: true
Nested Objects
var customer = new Customer
{
Name = "John Doe",
Address = new Address
{
Street = "123 Main St",
City = "New York",
ZipCode = "10001"
}
};
string toon = ToonSerializer.Serialize(customer);
public class Address
{
public string Street { get; set; } = "";
public string City { get; set; } = "";
public string ZipCode { get; set; } = "";
}
public class Customer
{
public string Name { get; set; } = "";
public Address Address { get; set; }
}
Output:
Name: John Doe
Address:
Street: 123 Main St
City: New York
ZipCode: "10001"
Strings that would otherwise read as a number, boolean or null (such as "10001") are quoted so they stay strings.
Collections of Objects
var employees = new List<Employee>
{
new() { Name = "Alice", Department = "Engineering", Salary = 85000 },
new() { Name = "Bob", Department = "Marketing", Salary = 65000 },
new() { Name = "Charlie", Department = "Sales", Salary = 70000 }
};
string toon = ToonSerializer.Serialize(employees);
public class Employee
{
public string Name { get; set; } = "";
public string Department { get; set; } = "";
public int Salary { get; set; }
}
Output:
[3]{Name,Department,Salary}:
Alice,Engineering,85000
Bob,Marketing,65000
Charlie,Sales,70000
Nullable Types
Nullable Value Types
var example1 = new NullableExample { Age = 25, BirthDate = null };
string toon1 = ToonSerializer.Serialize(example1);
// Output:
// Age: 25
// BirthDate: null
var example2 = new NullableExample { Age = null, BirthDate = new DateTime(2026, 1, 24, 17, 0, 0, DateTimeKind.Utc) };
string toon2 = ToonSerializer.Serialize(example2);
// Output:
// Age: null
// BirthDate: "2026-01-24T17:00:00Z"
public class NullableExample
{
public int? Age { get; set; }
public DateTime? BirthDate { get; set; }
}
Nullable Reference Types
var person = new Person
{
Name = "John",
MiddleName = null,
Email = "john@example.com"
};
string toon = ToonSerializer.Serialize(person);
public class Person
{
public string Name { get; set; } = string.Empty;
public string? MiddleName { get; set; }
public string? Email { get; set; }
}
Output:
Name: John
MiddleName: null
Email: john@example.com
Enums
Simple Enum
var task = new TodoItem { Title = "Review PR", Status = Status.Active };
string toon = ToonSerializer.Serialize(task);
public enum Status
{
Pending,
Active,
Completed,
Cancelled
}
public class TodoItem
{
public string Title { get; set; } = "";
public Status Status { get; set; }
}
Output:
Title: Review PR
Status: Active
Enum Flags
var permissions = Permissions.Read | Permissions.Write;
string toon = ToonSerializer.Serialize(permissions);
// Output: "Read, Write"
[Flags]
public enum Permissions
{
None = 0,
Read = 1,
Write = 2,
Execute = 4,
Delete = 8
}
DateTime and DateTimeOffset
var evt = new Event
{
Name = "Conference 2026",
EventDate = new DateTime(2026, 06, 15, 9, 0, 0),
RegisteredAt = new DateTimeOffset(2026, 1, 24, 17, 0, 0, TimeSpan.Zero)
};
string toon = ToonSerializer.Serialize(evt);
public class Event
{
public string Name { get; set; } = "";
public DateTime EventDate { get; set; }
public DateTimeOffset RegisteredAt { get; set; }
}
Output:
Name: Conference 2026
EventDate: "2026-06-15T09:00:00"
RegisteredAt: "2026-01-24T17:00:00+00:00"
Common Patterns
Optional Properties
var user = new User
{
Id = 123,
Username = "alice",
Bio = "Software Engineer"
// Website is null
};
string toon = ToonSerializer.Serialize(user);
public class User
{
public int Id { get; set; }
public string Username { get; set; } = "";
public string? Bio { get; set; } // Optional
public string? Website { get; set; } // Optional
}
Output:
Id: 123
Username: alice
Bio: Software Engineer
Website: null
Nested Collections
var dept = new Department
{
Name = "Engineering",
Teams = new List<string> { "Backend", "Frontend", "DevOps" }
};
string toon = ToonSerializer.Serialize(dept);
public class Department
{
public string Name { get; set; } = "";
public List<string> Teams { get; set; }
}
Output:
Name: Engineering
Teams[3]: Backend,Frontend,DevOps
Deserialization Examples
From String
string toonInput = """
Name: Alice
Email: alice@example.com
""";
var person = ToonSerializer.Deserialize<Person>(toonInput); // the Person of "Nullable Reference Types"
From File
// Async file deserialization; AppConfig is your settings class
var config = await ToonSerializer.DeserializeFromFileAsync<AppConfig>("appsettings.toon");
From Stream
using System.Text;
using var stream = new MemoryStream(Encoding.UTF8.GetBytes("Name: Alice\nEmail: alice@example.com"));
var person = await ToonSerializer.DeserializeFromStreamAsync<Person>(stream); // also an HTTP response or file stream
Error Handling
using ToonNet.Core;
using ToonNet.Core.Serialization;
try
{
var person = ToonSerializer.Deserialize<Person>("Name: Alice\nAge: abc");
}
catch (ToonParseException ex)
{
// Invalid TOON text (strict mode is on by default)
Console.WriteLine($"Parse error at line {ex.Line}, column {ex.Column}");
}
catch (ToonSerializationException ex)
{
// Valid TOON that does not fit the target type, e.g. "Age: abc"
Console.WriteLine($"Serialization error: {ex.Message}");
Console.WriteLine($"Path: {ex.Path}, Type: {ex.TargetType}"); // Path: $.Age, Type: System.Int32
}
public class Person
{
public string Name { get; set; } = "";
public int Age { get; set; }
}
Best Practices
- Use nullable types for optional properties
- Initialize collections to avoid null checks
- Use record types for immutable data
- Handle exceptions appropriately in production
- Use async methods for I/O operations
- Use streaming API for large datasets (millions of records)
Next Steps
- Serialization: Deep dive into serialization options and streaming API
- Deserialization: Advanced deserialization techniques
- Configuration: Customize serialization behavior
- Performance Tuning: Optimize for large datasets with streaming