serialization

Imported from wshaddix/dotnet-skills (skills/serialization/SKILL.md) via skills.sh. Install upstream with npx skills add wshaddix/dotnet-skills --skill serialization. Copyright stays with the author.

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

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

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

Formats to Avoid

System.Text.Json with Source Generators

For JSON serialization, use System.Text.Json with source generators for AOT compatibility and performance.

Basic Setup

using System.Text.Json.Serialization;

[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(List<Order>))]
[JsonSerializable(typeof(OrderStatus))]
public partial class AppJsonContext : JsonSerializerContext
{
}

Using the Generated Context

// Serialize
string json = JsonSerializer.Serialize(order, AppJsonContext.Default.Order);

// Deserialize
Order? result = JsonSerializer.Deserialize(json, AppJsonContext.Default.Order);

// With options
var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    TypeInfoResolver = AppJsonContext.Default
};

string json = JsonSerializer.Serialize(order, options);

ASP.NET Core Integration

var builder = WebApplication.CreateBuilder(args);

// Minimal APIs
builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
});

// MVC Controllers
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.TypeInfoResolverChain.Insert(0, AppJsonContext.Default);
    });

Combining Multiple Contexts

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.TypeInfoResolver = JsonTypeInfoResolver.Combine(
        AppJsonContext.Default,
        CatalogJsonContext.Default,
        InventoryJsonContext.Default
    );
});

Common Configuration

[JsonSourceGenerationOptions(
    PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase,
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
    WriteIndented = false)]
[JsonSerializable(typeof(Order))]
[JsonSerializable(typeof(List<Order>))]
public partial class AppJsonContext : JsonSerializerContext
{
}

Handling Polymorphism

[JsonDerivedType(typeof(CreditCardPayment), "credit_card")]
[JsonDerivedType(typeof(BankTransferPayment), "bank_transfer")]
[JsonDerivedType(typeof(WalletPayment), "wallet")]
public abstract class Payment
{
    public decimal Amount { get; init; }
    public string Currency { get; init; } = "USD";
}

public class CreditCardPayment : Payment
{
    public string Last4Digits { get; init; } = "";
}

[JsonSerializable(typeof(Payment))]
public partial class AppJsonContext : JsonSerializerContext
{
}

Protocol Buffers (Protobuf)

Best for: Actor systems, gRPC, event sourcing, any long-lived wire format.

Packages

<PackageReference Include="Google.Protobuf" Version="3.*" />
<PackageReference Include="Grpc.Tools" Version="2.*" PrivateAssets="All" />

Proto File

syntax = "proto3";

import "google/protobuf/timestamp.proto";

option csharp_namespace = "MyApp.Contracts";

message OrderMessage {
  int32 id = 1;
  string customer_id = 2;
  repeated OrderItemMessage items = 3;
  google.protobuf.Timestamp created_at = 4;
}

message OrderItemMessage {
  string product_id = 1;
  int32 quantity = 2;
  double unit_price = 3;
}

Standalone Protobuf (Without gRPC)

using Google.Protobuf;

// Serialize to bytes
byte[] bytes = order.ToByteArray();

// Deserialize from bytes
var restored = OrderMessage.Parser.ParseFrom(bytes);

// Serialize to stream
using var stream = File.OpenWrite("order.bin");
order.WriteTo(stream);

Proto File Registration in .csproj

<ItemGroup>
  <Protobuf Include="Protos\*.proto" GrpcServices="Both" />
</ItemGroup>

Versioning Rules

// SAFE: Add new fields with new numbers
message Order {
  string id = 1;
  string customer_id = 2;
  string shipping_address = 5;  // NEW - safe
}

// SAFE: Remove fields (keep the number reserved)
message Order {
  string id = 1;
  reserved 2;  // customer_id removed
}

// UNSAFE: Change field types
message Order {
  int32 id = 1;  // Was: string - BREAKS!
}

// UNSAFE: Reuse field numbers
message Order {
  reserved 2;
  string new_field = 2;  // Reusing 2 - BREAKS!
}

MessagePack

Best for: High-performance scenarios, compact payloads, actor messaging.

Packages

<PackageReference Include="MessagePack" Version="3.*" />
<PackageReference Include="MessagePack.SourceGenerator" Version="3.*" />

Basic Usage with Source Generator (AOT-Safe)

using MessagePack;

[MessagePackObject]
public partial class Order
{
    [Key(0)]
    public int Id { get; init; }

    [Key(1)]
    public string CustomerId { get; init; } = "";

    [Key(2)]
    public List<OrderItem> Items { get; init; } = [];

    [Key(3)]
    public DateTimeOffset CreatedAt { get; init; }

    [Key(4)]
    public string? Notes { get; init; }
}

Serialization

// Serialize
byte[] bytes = MessagePackSerializer.Serialize(order);

// Deserialize
var restored = MessagePackSerializer.Deserialize<Order>(bytes);

// With compression (LZ4)
var lz4Options = MessagePackSerializerOptions.Standard.WithCompression(
    MessagePackCompression.Lz4BlockArray);
byte[] compressed = MessagePackSerializer.Serialize(order, lz4Options);

AOT Resolver Setup

MessagePackSerializer.DefaultOptions = MessagePackSerializerOptions.Standard
    .WithResolver(GeneratedResolver.Instance);

Wire Compatibility Patterns

Tolerant Reader

Old code must safely ignore unknown fields:

// Protobuf/MessagePack: Automatic - unknown fields skipped
// System.Text.Json: Configure to allow
var options = new JsonSerializerOptions
{
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Skip
};

Introduce Read Before Write

Deploy deserializers before serializers for new formats:

// Phase 1: Add deserializer (deployed everywhere)
public Order Deserialize(byte[] data, string manifest) => manifest switch
{
    "Order.V1" => DeserializeV1(data),
    "Order.V2" => DeserializeV2(data),  // NEW - can read V2
    _ => throw new NotSupportedException()
};

// Phase 2: Enable serializer (after V1 deployed everywhere)
public (byte[] data, string manifest) Serialize(Order order) =>
    _useV2Format
        ? (SerializeV2(order), "Order.V2")
        : (SerializeV1(order), "Order.V1");

Never Embed Type Names

// BAD: Type name in payload - renaming class breaks wire format
{
    "$type": "MyApp.Order, MyApp",
    "id": 123
}

// GOOD: Explicit discriminator - refactoring safe
{
    "type": "order",
    "id": 123
}

Performance Comparison

Approximate throughput (higher is better):

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)

// BAD: Reflection-based -- fails under AOT/trimming
var json = JsonConvert.SerializeObject(order);
var order = JsonConvert.DeserializeObject<Order>(json);

// GOOD: Source-generated -- AOT-safe
var json = JsonSerializer.Serialize(order, AppJsonContext.Default.Order);
var order = JsonSerializer.Deserialize(json, AppJsonContext.Default.Order);

System.Text.Json Without Source Generators

// BAD: No context -- uses runtime reflection
var json = JsonSerializer.Serialize(order);

// GOOD: Explicit context -- uses source-generated code
var json = JsonSerializer.Serialize(order, AppJsonContext.Default.Order);

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:

akka {
  actor {
    serializers {
      messagepack = "Akka.Serialization.MessagePackSerializer, Akka.Serialization.MessagePack"
    }
    serialization-bindings {
      "MyApp.Messages.IMessage, MyApp" = messagepack
    }
  }
}

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/