Serialization

The serialization module converts objects to and from JSON, XML, YAML and TOML. You mark a class with [Serializer] to pick a format, then call GetSerializer() on an instance to get a SerializerConverter<T>. The converter can turn the object into a string, an XmlDocument, a JToken or a stream, and it can deserialize, load from a file or save to a file.

You can also use the adapters (NewtonsoftJsonSerializerAdapter, JsonSerializerAdapter, XmlSerializerAdapter, YamlSerializerAdapter, TomlSerializerAdapter) on their own, without the attribute or the factory.

How it works

SerializerFactory.GetSerializer(obj) reads the SerializerAttribute from the runtime type of obj and wraps the object in a SerializerConverter<T> with an adapter for that format:

The factory always uses Newtonsoft.Json for JSON. The System.Text.Json adapter (JsonSerializerAdapter) is only used if you create it yourself.

Attribute lookup rules:

• The attribute is read from the object's runtime type. SerializerAttribute is declared with Inherited = false, so a derived class needs its own [Serializer].
• For an array, the attribute is read from the element type (Customer[] uses the attribute on Customer).
• For any other IEnumerable, the attribute is read from the first generic argument (List<Customer> uses the attribute on Customer).
• If no attribute is found, GetSerializer throws InvalidOperationException with the message The CrispyWaffle.Serialization.SerializerAttribute attribute was not found in the object of type ....

Strict and non-strict JSON differ only when you deserialize. Strict mode uses MissingMemberHandling.Error, so a JSON property with no matching .NET member throws. Non-strict mode uses MissingMemberHandling.Ignore. Both modes use the pt-BR culture, NullValueHandling.Ignore and the Newtonsoft NotNullObserverConverter.

XmlSerializerAdapter, NewtonsoftJsonSerializerAdapter, YamlSerializerAdapter and TomlSerializerAdapter have no constructor dependencies, so the service locator can create them without registration.

Not-null observer

NotNullObserver is an empty marker class. Use it as the type of a property that you expect to always be null or empty in incoming JSON, such as a field a third-party API documents but never fills. Both JSON adapters register a matching converter by default. When the JSON has a real value for that property, the converter throws NotNullObserverException, and the adapter wraps it in a second NotNullObserverException that names the target type. This lets you detect when the upstream payload changes.

The two converters accept different "empty" values:

Note: the System.Text.Json converter calls JsonElement.EnumerateObject() before it checks the value kind. That call throws InvalidOperationException for any value that is not an object, and System.Text.Json wraps it in a JsonException ("The JSON value could not be converted to CrispyWaffle.Serialization.NotNullObserver"). In those cases you get JsonException instead of NotNullObserverException.

Getting started

using System;
using CrispyWaffle.Serialization;

var customer = new Customer { Id = 1, Name = "Jane Doe" };

// Serialize to a JSON string (Newtonsoft.Json, indented).
var json = (string)customer.GetSerializer();

// Deserialize back into a new instance.
Customer copy = SerializerFactory.GetSerializer<Customer>().Deserialize(json);

Console.WriteLine(copy.Name);

[Serializer(SerializerFormat.Json)]
public class Customer
{
    public int Id { get; set; }

    public string Name { get; set; }
}

Reference

SerializerFactory

public static class SerializerFactory — creates SerializerConverter<T> instances from the [Serializer] attribute or from an explicit format.

SerializerConverter<T>

public sealed class SerializerConverter<T> where T : class — wraps an object and an ISerializerAdapter, and exposes conversion operators and file helpers.

Methods that deserialize or load replace the wrapped object and return it.

ISerializerAdapter

public interface ISerializerAdapter — contract for a format-specific serializer. All methods have the constraint T : class.

IStringSerializerAdapter

public interface IStringSerializerAdapter : ISerializerAdapter — an adapter that can serialize directly to a string. SerializerConverter<T> uses it for the explicit string conversion.

BaseSerializerAdapter

public abstract class BaseSerializerAdapter : ISerializerAdapter — base class with file handling. Subclass it to add a format.

NewtonsoftJsonSerializerAdapter

public sealed class NewtonsoftJsonSerializerAdapter : BaseSerializerAdapter — JSON adapter based on Newtonsoft.Json. The factory uses it for all JSON.

JsonSerializerAdapter

public sealed class JsonSerializerAdapter : BaseSerializerAdapter — JSON adapter based on System.Text.Json. The factory never selects it; create it directly.

XmlSerializerAdapter

public sealed class XmlSerializerAdapter : BaseSerializerAdapter — XML adapter based on System.Xml.Serialization.XmlSerializer.

YamlSerializerAdapter

public sealed class YamlSerializerAdapter : BaseSerializerAdapter, IStringSerializerAdapter — YAML adapter based on YamlDotNet. Property names use camel case (ApplicationName becomes applicationName).

TomlSerializerAdapter

public sealed class TomlSerializerAdapter : BaseSerializerAdapter, IStringSerializerAdapter — TOML adapter based on Tomlyn. Property names use camel case (ApplicationName becomes applicationName).

SerializerAttribute

public sealed class SerializerAttribute : Attribute — selects the format the factory uses for a class or interface.

Declared with AttributeTargets.Class | AttributeTargets.Interface, Inherited = false, AllowMultiple = true. The factory reads it with Attribute.GetCustomAttribute, which throws AmbiguousMatchException if the attribute is applied more than once, so apply it only once per type.

SerializerFormat

public enum SerializerFormat — output format. Each value has a [HumanReadable] label.

NotNullObserver

public class NotNullObserver — empty marker type for properties that should never receive a value. See Not-null observer.

CrispyWaffle.Serialization.NewtonsoftJson.NotNullObserverConverter

public sealed class NotNullObserverConverter : JsonConverter (Newtonsoft) — enforces NotNullObserver properties during Newtonsoft deserialization.

CrispyWaffle.Serialization.NewtonsoftJson.NotNullObserverException

public class NotNullObserverException : Exception — thrown by the Newtonsoft converter and adapter when a NotNullObserver property has a value.

CrispyWaffle.Serialization.SystemTextJson.NotNullObserverConverter

public sealed class NotNullObserverConverter : JsonConverter<NotNullObserver> (System.Text.Json) — enforces NotNullObserver properties during System.Text.Json deserialization.

CrispyWaffle.Serialization.SystemTextJson.NotNullObserverException

public class NotNullObserverException : Exception — thrown by the System.Text.Json converter and adapter when a NotNullObserver property has a value.

The two exception classes have the same name in different namespaces. Catch the one that matches the adapter you use.

LocalFileNotFoundException

public class LocalFileNotFoundException : Exception (namespace CrispyWaffle.Serialization.Adapters) — thrown by BaseSerializerAdapter.Load<T> when the file does not exist.

Examples

XML round trip

[Serializer] with no arguments selects XML.

using CrispyWaffle.Serialization;

var order = new Order { Code = 42, Description = "Sample" };

var xml = (string)order.GetSerializer();

Order copy = SerializerFactory.GetSerializer<Order>().Deserialize(xml);

[Serializer]
public class Order
{
    public int Code { get; set; }

    public string Description { get; set; }
}

Collections

Arrays and generic collections use the attribute of their element type.

using System.Collections.Generic;
using CrispyWaffle.Serialization;

var items = new List<Customer>
{
    new() { Id = 1, Name = "Jane" },
    new() { Id = 2, Name = "John" },
};

var json = (string)items.GetSerializer();

List<Customer> copy = new List<Customer>().GetSerializer().Deserialize(json);

[Serializer(SerializerFormat.Json)]
public class Customer
{
    public int Id { get; set; }

    public string Name { get; set; }
}

Save to and load from a file

using CrispyWaffle.Serialization;

var settings = new AppSettings { Endpoint = "https://example.com" };

settings.GetSerializer().Save("settings.json");

AppSettings loaded = SerializerFactory.GetSerializer<AppSettings>().Load("settings.json");

[Serializer(SerializerFormat.Json, false)]
public class AppSettings
{
    public string Endpoint { get; set; }
}

Force a format without an attribute

GetCustomSerializer ignores the attribute, so it also works for types without one.

using CrispyWaffle.Serialization;
using Newtonsoft.Json.Linq;

var point = new Point { X = 1, Y = 2 };

JToken token = point.GetCustomSerializer(SerializerFormat.Json);

public class Point
{
    public int X { get; set; }

    public int Y { get; set; }
}

YAML round trip

[Serializer(SerializerFormat.Yaml)] selects YAML. Property names are written in camel case.

using CrispyWaffle.Serialization;

var settings = new AppSettings { ApplicationName = "Crispy Waffle", RetryCount = 3 };

// applicationName: Crispy Waffle
// retryCount: 3
var yaml = (string)settings.GetSerializer();

AppSettings copy = SerializerFactory.GetSerializer<AppSettings>().Deserialize(yaml);

settings.GetSerializer().Save("settings.yaml");
AppSettings loaded = SerializerFactory.GetSerializer<AppSettings>().Load("settings.yaml");

[Serializer(SerializerFormat.Yaml)]
public class AppSettings
{
    public string ApplicationName { get; set; }

    public int RetryCount { get; set; }
}

To use YAML for a type whose attribute selects another format, call GetCustomSerializer(SerializerFormat.Yaml).

TOML round trip

[Serializer(SerializerFormat.Toml)] selects TOML. Property names are written in camel case.

using CrispyWaffle.Serialization;

var settings = new AppSettings { ApplicationName = "Crispy Waffle", RetryCount = 3 };

// applicationName = "Crispy Waffle"
// retryCount = 3
var toml = (string)settings.GetSerializer();

AppSettings copy = SerializerFactory.GetSerializer<AppSettings>().Deserialize(toml);

settings.GetSerializer().Save("settings.toml");
AppSettings loaded = SerializerFactory.GetSerializer<AppSettings>().Load("settings.toml");

[Serializer(SerializerFormat.Toml)]
public class AppSettings
{
    public string ApplicationName { get; set; }

    public int RetryCount { get; set; }
}

To use TOML for a type whose attribute selects another format, call GetCustomSerializer(SerializerFormat.Toml).

Use the System.Text.Json adapter directly

using System.IO;
using CrispyWaffle.Serialization.Adapters;

var adapter = new JsonSerializerAdapter();

adapter.Serialize(new Point { X = 1, Y = 2 }, out Stream stream);
var json = new StreamReader(stream).ReadToEnd();

Point copy = adapter.Deserialize<Point>(json);

public class Point
{
    public int X { get; set; }

    public int Y { get; set; }
}

Detect an unexpected value

LegacyField is expected to always be empty. When it is not, deserialization fails.

using System;
using CrispyWaffle.Serialization;
using CrispyWaffle.Serialization.Adapters;
using CrispyWaffle.Serialization.NewtonsoftJson;

var adapter = new NewtonsoftJsonSerializerAdapter();

try
{
    adapter.Deserialize<Payload>("{\"Id\":1,\"LegacyField\":\"surprise\"}");
}
catch (NotNullObserverException e)
{
    // "Unable to serialize type Payload. Constraints: Not null observer"
    Console.WriteLine(e.Message);
    Console.WriteLine(e.InnerException?.Message);
}

public class Payload
{
    public int Id { get; set; }

    public NotNullObserver LegacyField { get; set; }
}

See also

• Service locator
• Attributes
• Logging