JSON and binary serialization patterns for .NET applications, including System.Text.Json source generators, Protocol Buffers, MessagePack, and AOT-compatible best practices. Use when configuring JSON serialization, choosing between formats, implementing Protocol Buffers for high-performance scenario

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 Serialization Format Comparison Format Library AOT Safe Human Readable Relative Size Relative Speed Best For JSON System.Text.Json (source gen) Yes Yes Largest Good APIs, config, web clients Protobuf Google.Protobuf Yes No Smallest Fastest Service to service, gRPC wire format MessagePack MessagePack CSharp Yes (with AOT resolver) No Small Fast High throughput caching, real time JSON Newtonsoft.Json No (reflection) Yes Largest Slower Legacy only do not use for AOT When to Choose What System.Text.Json with source generators : Default choice for APIs, configuration, and any scenario where human readable output or web client consumption matters. AOT safe. Protobuf : Default wire format for gRPC. Best throughput and smallest payload size for service to service communication. Schema first development with .proto files. MessagePack : When you need binary compactness without .proto schema management. Good for caching layers, real time messaging, and high throughput scenarios. 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. 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. Basic Setup Using the Generated Context ASP.NET Core Integration Combining Multiple Contexts Common Configuration Handling Polymorphism Protocol Buffers (Protobuf) Best for: Actor systems, gRPC, event sourcing, any long lived wire format. Packages Proto File Standalone Protobuf (Without gRPC) Proto File Registration in .csproj Versioning Rules MessagePack Best for: High performance scenarios, compact payloads, actor messaging. Packages Basic Usage with Source Generator (AOT Safe) Serialization AOT Resolver Setup 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 ★★☆☆☆ ★★☆☆☆ ★★★☆☆ Optimization Tips Reuse JsonSerializerOptions creating options is expensive Use JsonSerializerContext eliminates warm up cost Use Utf8JsonWriter / Utf8JsonReader for streaming scenarios Use Protobuf ByteString for binary data instead of base64 encoded strings Enable MessagePack LZ4 compression for large payloads Anti Patterns: Reflection Based Serialization Do not use reflection based serializers in Native AOT or trimming scenarios. Newtonsoft.Json (JsonConvert) System.Text.Json Without Source Generators Migration Path from Newtonsoft.Json 1. Replace JsonConvert.SerializeObject / DeserializeObject with JsonSerializer.Serialize / Deserialize 2. Replace [JsonProperty] with [JsonPropertyName] 3. Replace JsonConverter base class with JsonConverter<T from System.Text.Json 4. Create a JsonSerializerContext with [JsonSerializable] for all serialized types 5. Replace JObject / JToken dynamic access with JsonDocument / JsonElement or strongly typed models 6. Test serialization round trips attribute semantics differ Akka.NET Serialization For Akka.NET actor systems, use schema based serialization: Key Principles Default to System.Text.Json with source generators for all JSON serialization Use Protobuf for service to service binary serialization Use MessagePack for high throughput caching and real time Never use Newtonsoft.Json for new AOT targeted projects Always register JsonSerializerContext in ASP.NET Core Annotate all serialized types source generators only generate code for listed types Agent Gotchas 1. Do not use JsonSerializer.Serialize(obj) without a context in AOT projects it falls back to reflection. 2. Do not forget to list collection types in [JsonSerializable] [JsonSerializable(typeof(Order))] does not cover List<Order . 3. Do not use Newtonsoft.Json [JsonProperty] attributes with System.Text.Json they are silently ignored. 4. Do not mix MessagePack [Key] integer keys with [Key] string keys in the same type hierarchy. 5. Do not omit GrpcServices attribute on <Protobuf items without it, both client and server stubs are generated. Resources System.Text.Json Source Generation : https://learn.microsoft.com/en us/dotnet/standard/serialization/system text json/source generation Migrate from Newtonsoft.Json to System.Text.Json : https://learn.microsoft.com/en us/dotnet/standard/serialization/system text json/migrate from newtonsoft 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 Native AOT deployment : https://learn.microsoft.com/en us/dotnet/core/deploying/native aot/