Serialization

This is a reference guide for picking serialization formats in .NET, with a strong opinion: use schema-based formats like Protobuf or MessagePack over reflection-based ones like Newtonsoft.Json. It walks you through System.Text.Json with source generators for AOT compatibility, shows you how to version Protobuf schemas without breaking old readers, and explains when to use what (gRPC gets Protobuf, caching gets MessagePack, REST APIs get System.Text.Json). The migration section from Newtonsoft is solid, covering the attribute differences and polymorphism gotchas. If you're building distributed systems or planning for Native AOT, the wire compatibility patterns alone are worth reading.

skills.sh installs: 596
GitHub stars: 1.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add aaronontheweb/dotnet-skills --skill serialization --agent claude-code

Installs into .claude/skills of the current project.

Files

Serialization in .NET

When to Use This Skill

Use this skill when:

Choosing a serialization format for APIs, messaging, or persistence
Migrating from Newtonsoft.Json to System.Text.Json
Implementing AOT-compatible serialization
Designing wire formats for distributed systems
Optimizing serialization performance

Schema-Based vs Reflection-Based

Aspect	Schema-Based	Reflection-Based
Examples	Protobuf, MessagePack, System.Text.Json (source gen)	Newtonsoft.Json, BinaryFormatter
Type info in payload	No (external schema)	Yes (type names embedded)
Versioning	Explicit field numbers/names	Implicit (type structure)
Performance	Fast (no reflection)	Slower (runtime reflection)
AOT compatible	Yes	No
Wire compatibility	Excellent	Poor