Choose the right serialization format for .NET applications. Prefer schema-based formats (Protobuf, MessagePack) over reflection-based (Newtonsoft.Json). Use System.Text.Json with AOT source generators for JSON scenarios.

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 For JSON serialization, use System.Text.Json with source generators for AOT compatibility and performance. Setup Usage Benefits No reflection at runtime All type info generated at compile time AOT compatible Works with Native AOT publishing Faster No runtime type analysis Trim safe Linker knows exactly what's needed Protocol Buffers (Protobuf) Best for: Actor systems, gRPC, event sourcing, any long lived wire format. Setup Define Schema Versioning Rules MessagePack Best for: High performance scenarios, compact payloads, actor messaging. Setup Usage with Contracts AOT Compatible Setup Migrating from Newtonsoft.Json Common Issues Newtonsoft System.Text.Json Fix $type in JSON Not supported by default Use discriminators or custom converters JsonProperty JsonPropertyName Different attribute DefaultValueHandling DefaultIgnoreCondition Different API NullValueHandling DefaultIgnoreCondition Different API Private setters Requires [JsonInclude] Explicit opt in Polymorphism [JsonDerivedType] (.NET 7+) Explicit discriminators Migration Pattern Polymorphism with Discriminators Wire Compatibility Patterns Tolerant Reader Old code must safely ignore unknown fields: Introduce Read Before Write Deploy deserializers before serializers for new formats: Never Embed Type Names Performance Comparison Approximate throughput (higher is better): Format Serialize Deserialize Size MessagePack ★★★★★ ★★★★★ ★★★★★ Protobuf ★★★★★ ★★★★★ ★★★★★ System.Text.Json (source gen) ★★★★☆ ★★★★☆ ★★★☆☆ System.Text.Json (reflection) ★★★☆☆ ★★★☆☆ ★★★☆☆ Newtonsoft.Json ★★☆☆☆ ★★☆☆☆ ★★★☆☆ For hot paths, prefer MessagePack or Protobuf. Akka.NET Serialization For Akka.NET actor systems, use schema based serialization: See [Akka.NET Serialization Docs](https://getakka.net/articles/networking/serialization.html). Best Practices DO DON'T Resources System.Text.Json Source Generation : https://learn.microsoft.com/en us/dotnet/standard/serialization/system text json/source generation Protocol Buffers : https://protobuf.dev/ MessagePack CSharp : https://github.com/MessagePack CSharp/MessagePack CSharp Akka.NET Serialization : https://getakka.net/articles/networking/serialization.html Wire Compatibility : https://getakka.net/community/contributing/wire compatibility.html