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

Recommendation: Use schema-based serialization for anything that crosses process boundaries.

---

Format Recommendations

Use Case	Recommended Format	Why
REST APIs	System.Text.Json (source gen)	Standard, AOT-compatible
gRPC	Protocol Buffers	Native format, excellent versioning
Actor messaging	MessagePack or Protobuf	Compact, fast, version-safe
Event sourcing	Protobuf or MessagePack	Must handle old events forever
Caching	MessagePack	Compact, fast
Configuration	JSON (System.Text.Json)	Human-readable
Logging	JSON (System.Text.Json)	Structured, parseable

Formats to Avoid

Format	Problem
BinaryFormatter	Security vulnerabilities, deprecated, never use
Newtonsoft.Json default	Type names in payload break on rename
DataContractSerializer	Complex, poor versioning
XML	Verbose, slow, complex

---

System.Text.Json with Source Generators