Custom Converters
Create custom type converters for specialized serialization/deserialization logic.
IToonConverter Interface
The converter types live in the ToonNet.Core.Serialization namespace; the ToonValue types
(ToonString, ToonNumber, ToonObject, ...) live in ToonNet.Core.Models.
public interface IToonConverter
{
bool CanConvert(Type type);
ToonValue? Write(object? value, ToonSerializerOptions options);
object? Read(ToonValue value, Type targetType, ToonSerializerOptions options);
}
public interface IToonConverter<T> : IToonConverter
{
ToonValue? Write(T? value, ToonSerializerOptions options);
T? Read(ToonValue value, ToonSerializerOptions options);
}
ToonConverter Base Class
Extend ToonConverter<T> for type-specific converters. It implements the non-generic members for you:
public abstract class ToonConverter<T> : IToonConverter<T>
{
// Matches T and types derived from T. Override to narrow it.
public virtual bool CanConvert(Type type) => typeof(T).IsAssignableFrom(type);
public abstract ToonValue? Write(T? value, ToonSerializerOptions options);
public abstract T? Read(ToonValue value, ToonSerializerOptions options);
}
How the serializer calls a converter:
Writeis not called fornull; the serializer writesnullitself (or skips the property whenIgnoreNullValuesis set).Readis called for anullvalue, with aToonNull, so handle it for reference types.- When writing, a converter of the options for the value's runtime type is used first, otherwise one for its declared type: a property's type, a collection's item type or a dictionary's value type (since 4.0 for items and dictionary values too).
- The
optionsargument lets a converter serialize nested values withToonSerializer.SerializeToValueandToonSerializer.DeserializeFromValue.
Example: DateTime Converter
using System.Globalization;
using ToonNet.Core;
using ToonNet.Core.Models;
using ToonNet.Core.Serialization;
public class CustomDateTimeConverter : ToonConverter<DateTime>
{
private const string Format = "yyyy-MM-dd HH:mm:ss";
public override ToonValue? Write(DateTime value, ToonSerializerOptions options)
{
return new ToonString(value.ToString(Format, CultureInfo.InvariantCulture));
}
public override DateTime Read(ToonValue value, ToonSerializerOptions options)
{
if (value is not ToonString str)
throw new ToonSerializationException("Expected string for DateTime");
if (!DateTime.TryParseExact(str.Value, Format, CultureInfo.InvariantCulture,
DateTimeStyles.None, out DateTime result))
throw new ToonSerializationException($"Expected a date in the format {Format}"); // not the value: it may be personal data
return result;
}
}
Output for a DateTime property: When: "2026-06-15 09:00:00" (quoted because the value contains a :).
Example: URI Converter
Uri is supported out of the box; a converter is only needed for different rules, such as accepting
absolute http and https URIs only (on Linux and macOS, Uri.TryCreate("/path", UriKind.Absolute, ...) succeeds
with a file:// URI, so the scheme is checked too):
public class AbsoluteUriConverter : ToonConverter<Uri>
{
public override ToonValue? Write(Uri? value, ToonSerializerOptions options)
{
return new ToonString(value!.ToString()); // never called with null
}
public override Uri? Read(ToonValue value, ToonSerializerOptions options)
{
if (value is ToonNull)
return null;
if (value is not ToonString str)
throw new ToonSerializationException("Expected string for Uri");
if (!Uri.TryCreate(str.Value, UriKind.Absolute, out Uri? uri) || uri.Scheme is not ("http" or "https"))
throw new ToonSerializationException("Expected an absolute http or https URI");
return uri;
}
}
Registering Converters
var options = new ToonSerializerOptions();
options.AddConverter(new CustomDateTimeConverter()); // same as options.Converters.Add(...), with a null check
options.AddConverter(new AbsoluteUriConverter());
string toon = ToonSerializer.Serialize(obj, options);
var result = ToonSerializer.Deserialize<MyType>(toon, options);
The first converter whose CanConvert returns true is used.
With the [ToonConverter] Attribute
Apply [ToonConverter] (namespace ToonNet.Core.Serialization.Attributes) to a property, or to a class
or struct, to use a converter without registering it in the options. The converter type needs a public
parameterless constructor.
using ToonNet.Core.Serialization.Attributes;
public class Order
{
[ToonConverter(typeof(CustomDateTimeConverter))]
public DateTime PlacedAt { get; set; }
}
A converter on a property takes precedence over the converters in the options, which take precedence over a converter on the type.
Complex Example: Custom Object Converter
public class AddressConverter : ToonConverter<Address>
{
public override ToonValue? Write(Address? value, ToonSerializerOptions options)
{
// Custom format: "Street, City, ZIP"
string formatted = $"{value!.Street}, {value.City}, {value.ZipCode}";
return new ToonString(formatted);
}
public override Address? Read(ToonValue value, ToonSerializerOptions options)
{
if (value is ToonNull)
return null;
if (value is not ToonString str)
throw new ToonSerializationException("Expected string");
string[] parts = str.Value.Split(", ");
if (parts.Length != 3)
throw new ToonSerializationException("Invalid address format");
return new Address
{
Street = parts[0],
City = parts[1],
ZipCode = parts[2]
};
}
}
An Address property is then written as Address: "1 Main St, New York, 10001".
Performance
Converters exchange ToonValue trees, but only for the values they convert: the rest of the document is still written
and read straight from the text. Generated code ([ToonSerializable]) does not consult converters, so the serializer
uses it for a type only when no converter applies to the type or to anything its generated code converts itself
(property, element, key and value types, and the types with generated code it reaches); for the other types it uses
reflection, or with the ToonTypeInfo overloads the generated tree-based methods, which consult the converters (no
reflection, for trimmed and NativeAOT apps). A converter for a type your models do not use costs nothing measurable; a
converter for int takes the fast path away from every model with an int property.
Error Handling
public class SafeConverter<T> : ToonConverter<T> where T : new()
{
public override ToonValue? Write(T? value, ToonSerializerOptions options)
{
try
{
// Serialization logic
return new ToonString(value!.ToString() ?? "");
}
catch (Exception ex)
{
throw new ToonEncodingException($"Failed to serialize {typeof(T).Name}", ex)
{
ProblematicValue = value
};
}
}
public override T? Read(ToonValue value, ToonSerializerOptions options)
{
try
{
// Deserialization logic
return new T();
}
catch (Exception ex)
{
throw new ToonSerializationException($"Failed to deserialize {typeof(T).Name}", ex)
{
TargetType = typeof(T)
};
}
}
}
See Also
- Type System: ToonValue types
- Converter Examples: More converter examples