serialization

Implements JSON, Protobuf, and MessagePack serialization patterns for AOT-compatible .NET applications.

Updated Mar 8, 2026
One-click install
npx skills add https://github.com/AGIBuild/dotnet.CI.template --skill serialization-agibuild
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: serialization
Source: https://github.com/AGIBuild/dotnet.CI.template/tree/main/.cursor/skills/serialization
Command: npx skills add https://github.com/AGIBuild/dotnet.CI.template --skill serialization-agibuild

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Choosing and configuring serialization in .NET is error-prone: reflection-based serializers break under Native AOT and trimming, Newtonsoft.Json attributes are silently ignored by System.Text.Json, and wire format changes can break compatibility across services. This Skill provides concrete, tested patterns for selecting and implementing the right serialization approach. ## Core Features & Use Cases - Format Selection Guidance: Compares System.Text.Json, Protocol Buffers, MessagePack, and Newtonsoft.Json across AOT safety, payload size, and speed so you pick the right format for APIs, gRPC services, or caching layers. - AOT-Safe Implementation Patterns: Provides ready-to-use code for System.Text.Json source generators, ASP.NET Core context registration, polymorphic type handling, MessagePack source-generated resolvers, and Protobuf schema setup. - Wire Compatibility & Migration: Covers versioning rules for Protobuf, tolerant-reader patterns, and a step-by-step migration path from Newtonsoft.Json to System.Text.Json. - Use Case: You are converting an ASP.NET Core API to Native AOT and need to replace all reflection-based JSON serialization with source-generated contexts, including polymorphic payment types and combined contexts across multiple assemblies. ## Quick Start Ask the agent to convert my Order model to AOT-safe JSON serialization using a System.Text.Json source-generated context registered in ASP.NET Core.

Frequently Asked Questions about serialization

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make System.Text.Json work with Native AOT?▼

Use source generators by defining a partial class inheriting JsonSerializerContext annotated with [JsonSerializable] for every serialized type, including collection types like List<Order>. Then pass the generated context, such as AppJsonContext.Default.Order, to JsonSerializer.Serialize and Deserialize calls.

Should I use Protobuf or MessagePack for service communication?▼

Protobuf is the default wire format for gRPC and service-to-service communication, offering schema-first development with .proto files and the smallest payloads. MessagePack suits high-throughput caching and real-time messaging when you want binary compactness without managing .proto schemas.

How do I migrate from Newtonsoft.Json to System.Text.Json?▼

Replace JsonConvert calls with JsonSerializer, swap [JsonProperty] for [JsonPropertyName], convert custom converters to JsonConverter<T>, and create a JsonSerializerContext listing all serialized types. Replace JObject dynamic access with JsonDocument or strongly-typed models, then test round-trips since attribute semantics differ.

Why is Newtonsoft.Json not compatible with Native AOT?▼

Newtonsoft.Json relies on runtime reflection to discover type members, which Native AOT and trimming remove at compile time. This causes serialization failures or missing data in AOT-published applications, so source-generated serializers are required instead.

What Protobuf changes break wire compatibility?▼

Changing an existing field's type or reusing a removed field's number breaks wire compatibility. Safe changes include adding new fields with unused numbers and removing fields while reserving their numbers with the reserved keyword.

Why is my [JsonSerializable] context not serializing collections?▼

Source generators only produce code for explicitly listed types, so [JsonSerializable(typeof(Order))] does not cover List<Order>. Add a separate [JsonSerializable(typeof(List<Order>))] attribute for each collection type you serialize.