A serializer that writes each member's value inline has two problems with real object graphs. An object reached through two members is written twice and comes back as two separate objects, and a cycle never terminates. Sphere10 Framework's binary serializers solve both by tracking the objects seen during one operation and writing a back-reference when an object appears again.

This article serializes a small graph that contains a shared object and a cycle, then shows how the mechanism works. It covers SerializerBuilder.FactoryAssemble, the role of SerializationContext and ReferenceSerializer<T>, and how to control reference handling for each member.

1. Define what must survive

The sample uses one node type with a name and two links of its own type.

public sealed class GraphNode {
	public string Name { get; set; }

	public GraphNode Primary { get; set; }

	public GraphNode Secondary { get; set; }
}

var root = new GraphNode { Name = "root" };
var shared = new GraphNode { Name = "shared", Primary = root };
root.Primary = shared;
root.Secondary = shared;

%%{init: {"flowchart": {"nodeSpacing": 20, "rankSpacing": 28}, "themeVariables": {"fontSize": "16px"}}}%%
flowchart TB
    R(["root"]) -->|"Primary"| S(["shared"])
    R -->|"Secondary"| S
    S -->|"Primary"| R

2. Serialize the binary graph in one operation

SerializerBuilder.FactoryAssemble<T>() builds a serializer for a type from its public read-write properties and fields, and assembles serializers for the member types it finds along the way.

var serializer = SerializerBuilder.FactoryAssemble<GraphNode>();
var bytes = serializer.SerializeToBytes(root, Endianness.LittleEndian);
var copy = serializer.DeserializeBytes(bytes, Endianness.LittleEndian);

copy is a new graph with the same shape as the original. copy.Primary and copy.Secondary are one object, and copy.Primary.Primary is copy itself.

3. How references are tracked

Every serializer call receives a SerializationContext, which records the objects that have been written or read so far in that operation. The convenience methods SerializeToBytes and DeserializeBytes create one context for the whole call and dispose it afterwards.

Automatic assembly wraps each reference-type member in a ReferenceSerializer<T>. That wrapper writes one prefix byte before the member and uses the context to decide what follows.

• 00 means the member is null, and nothing follows.
• 01 means the object is written in full after the prefix.
• 02 means the object was already written in this operation, and a variable-length context index follows.

---
config:
  packet:
    bitsPerRow: 16
    bitWidth: 22
    showBits: true
---
packet-beta
0: "01"
1-6: "Name: root"
7: "01"
8-15: "Name: shared"
16-17: "02 00"
18: "00"
19-20: "02 02"

On deserialization the same prefix tells the reader whether to return null, build a new object, or return the object it already built at the recorded index. An object is registered with the context as soon as it is activated, before its members are read, which is what allows a member to refer back to its own parent.

A back-reference is a single variable-length integer. A shared object therefore costs its full size once, however many members point to it.

4. Control reference handling for a member

ReferenceSerializerMode has three flags, and Default enables all of them.

The [ReferenceMode] attribute changes the mode of one member during automatic assembly.

[ReferenceMode(Nullable = false, AllowContextReference = false)]
public GraphNode Primary { get; set; }

With context references disabled, a repeated object is written in full each time and is restored as separate copies. A cycle through such a member cannot be written, and the serializer throws InvalidOperationException when it meets one. Writing a null through a member that does not support null also throws.

5. Limits of automatic assembly

6. Get the package and run the sample

Add the package to a .NET 10 project.

dotnet add package Sphere10.Framework --version 3.1.3

The serializers ship in the Sphere10.Framework NuGet package. Download the sample project. It round-trips the graph and checks the shared reference and the cycle with ReferenceEquals. Use the .NET 10 SDK and Sphere10 Framework 3.1.3.

dotnet run -c Release

Shared reference preserved: True
Cycle preserved: True
Name set through Primary, read through Secondary: renamed
Serialized bytes: 21

The third line is produced by renaming the node through Primary and reading the name through Secondary.

• Binary serialization guide
• Shared and cyclic reference tests

Download the complete NuGet sample project. The archive contains the project, its model files and run instructions. Keep the pinned package version when reproducing the example.

The Sphere10 Framework overview describes the rest of the toolkit.

Author: Herman Schoenfeld