Converter Examples
More converters for types that need another text form than the default one. The interface, the base class, the
order in which converters are chosen and the [ToonConverter] attribute are described in
Custom Converters, which also has a DateTime converter with a fixed format.
Write is never called with null; Read receives a ToonNull for null values.
Value Converters
Guid Without Hyphens
Guid is supported out of the box; a converter lets you pick another format:
using ToonNet.Core;
using ToonNet.Core.Models;
using ToonNet.Core.Serialization;
public class GuidConverter : ToonConverter<Guid>
{
public override ToonValue? Write(Guid value, ToonSerializerOptions options)
{
return new ToonString(value.ToString("N")); // 32 digits, no dashes
}
public override Guid Read(ToonValue value, ToonSerializerOptions options)
{
if (value is not ToonString str)
throw new ToonSerializationException("Expected string for Guid");
return Guid.Parse(str.Value);
}
}
Registering Converters
var options = new ToonSerializerOptions();
options.AddConverter(new CustomDateTimeConverter()); // from Custom Converters
options.AddConverter(new GuidConverter());
// Use for serialization
string toon = ToonSerializer.Serialize(obj, options);
// Use for deserialization
var result = ToonSerializer.Deserialize<MyData>(toon, options);
Advanced Examples
Complex Type Converter
public class AddressConverter : ToonConverter<Address>
{
public override ToonValue? Write(Address? value, ToonSerializerOptions options)
{
return new ToonObject
{
["street"] = value!.Street,
["city"] = value.City,
["zip"] = value.ZipCode
};
}
public override Address? Read(ToonValue value, ToonSerializerOptions options)
{
if (value is ToonNull)
return null;
if (value is not ToonObject obj)
throw new ToonSerializationException("Expected object");
return new Address
{
Street = (obj["street"] as ToonString)?.Value ?? "",
City = (obj["city"] as ToonString)?.Value ?? "",
ZipCode = (obj["zip"] as ToonString)?.Value ?? ""
};
}
}
Generic Collection Converter
public class CustomListConverter<T> : ToonConverter<List<T>>
{
public override ToonValue? Write(List<T>? value, ToonSerializerOptions options)
{
var array = new ToonArray();
foreach (var item in value!)
{
array.Add(ToonSerializer.SerializeToValue(item, options));
}
return array;
}
public override List<T>? Read(ToonValue value, ToonSerializerOptions options)
{
if (value is ToonNull)
return null;
if (value is not ToonArray arr)
throw new ToonSerializationException("Expected array");
var list = new List<T>();
foreach (var item in arr.Items)
{
list.Add(ToonSerializer.DeserializeFromValue<T>(item, options)!);
}
return list;
}
}
Best Practices
- Handle nulls: Check for
ToonNullin Read methods - Type validation: Validate
ToonValuetypes before casting - Error messages: Provide clear exception messages
- Immutability: Don't modify input
ToonValueobjects - Performance: Cache expensive operations
See Also
- Custom Converters: The converter interface and how converters are chosen
- JSON Integration: Converting JSON documents to and from TOON
- YAML Integration: Converting YAML documents to and from TOON
- Type System: ToonValue types