serialization_skill

Overview

This skill helps .NET developers choose and apply the right serialization format for APIs, messaging, caching, and persistence. It favors schema-based formats (Protobuf, MessagePack) and AOT-friendly JSON using System.Text.Json source generators. The guidance focuses on wire compatibility, performance, and migration from reflection-based serializers.

How this skill works

It evaluates use cases and recommends formats based on cross-process boundaries, versioning needs, and performance constraints. For JSON scenarios it prescribes System.Text.Json with source generation to remove runtime reflection and enable Native AOT. For long-lived or high-performance wire formats it recommends Protobuf or MessagePack with explicit schemas or keys.

When to use it

• Choosing serialization for REST APIs, gRPC, actor messages, event sourcing, caching, or logs
• Migrating away from Newtonsoft.Json to System.Text.Json (source gen)
• Designing wire formats that must remain compatible across versions and deployments
• Optimizing hot-path serialization for throughput and size
• Preparing code for Native AOT or constrained runtime environments

Best practices

• Prefer schema-based formats (Protobuf, MessagePack) for anything crossing process boundaries
• Use System.Text.Json with source generators for REST, configuration, and logging to be AOT-compatible and fast
• Define explicit field numbers/keys and keep removed fields reserved for version safety
• Deploy deserializers before new serializers (read-before-write) to enable safe rollouts
• Never embed CLR type names in payloads; use explicit discriminators instead
• Avoid BinaryFormatter and reflection-heavy serializers for security and performance reasons

Example use cases

• REST APIs and configuration: System.Text.Json with source-generated JsonSerializerContext
• gRPC and actor messaging: Protocol Buffers for compact, version-safe wire format
• High-throughput caching or actor messages: MessagePack with source generation and composite resolver
• Event sourcing: Protobuf or MessagePack to preserve long-lived event compatibility
• Migration: Replace Newtonsoft.Json usage with System.Text.Json source gen and add polymorphism with JsonDerivedType where needed