.NET 5 序列化重大变更：KeyValuePair 现在遵循命名策略和编码器选项

.NET 5 序列化重大变更：KeyValuePair 现在遵循命名策略和编码器选项

前言

在 .NET 5 中，System.Text.Json 序列化器对 KeyValuePair<TKey, TValue> 类型的处理方式发生了重要变化。本文将详细解析这一变更的内容、原因以及开发者需要注意的事项。

变更概述

在 .NET Core 3.x 和 System.Text.Json 4.6.0-4.7.2 版本中，KeyValuePair<TKey, TValue> 类型的序列化和反序列化行为有以下限制：

1. 序列化时总是使用固定的 "Key" 和 "Value" 属性名
2. 反序列化时严格要求 JSON 属性名必须为 "Key" 和 "Value"

从 .NET 5 开始，KeyValuePair<TKey, TValue> 的序列化和反序列化行为与其他 POCO 类型保持一致，会遵循以下选项设置：

• PropertyNamingPolicy：属性命名策略
• PropertyNameCaseInsensitive：属性名大小写不敏感
• Encoder：字符编码器

详细变更说明

序列化行为变化

旧行为 (.NET Core 3.x):

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// 输出: {"Key":1,"Value":1} (不遵循命名策略)

新行为 (.NET 5+):

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// 输出: {"key":1,"value":1} (遵循命名策略)

反序列化行为变化

旧行为 (.NET Core 3.x):

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";
// 抛出 JsonException，因为属性名不是 "Key" 和 "Value"
JsonSerializer.Deserialize<KeyValuePair<int, int>>(json, options);

新行为 (.NET 5+):

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";
// 成功反序列化
KeyValuePair<int, int> kvp = JsonSerializer.Deserialize<KeyValuePair<int, int>>(json);

为了保持向后兼容性，.NET 5 仍然会识别 "Key" 和 "Value" 这种原始命名方式。

变更原因

这一变更是基于开发者社区的反馈做出的。许多开发者期望 KeyValuePair<TKey, TValue> 的序列化行为能够与其他普通对象保持一致，特别是能够遵循指定的命名策略。

影响范围

这一变更会影响以下 API 的使用：

• JsonSerializer.Serialize 及其重载
• JsonSerializer.SerializeToUtf8Bytes
• JsonSerializer.SerializeAsync
• JsonSerializer.Deserialize 及其重载
• JsonSerializer.DeserializeAsync

应对建议

如果你的代码依赖于旧的行为，可以考虑以下解决方案：

1. 升级兼容：如果可能，建议升级代码以适应新的行为，这是最推荐的解决方案。

2. 使用自定义转换器：对于需要保持旧行为的场景，可以实现自定义的 JsonConverter：

public class LegacyKeyValuePairConverter<TKey, TValue> : JsonConverter<KeyValuePair<TKey, TValue>>
{
    public override KeyValuePair<TKey, TValue> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 实现旧版反序列化逻辑
    }

    public override void Write(Utf8JsonWriter writer, KeyValuePair<TKey, TValue> value, JsonSerializerOptions options)
    {
        // 实现旧版序列化逻辑
    }
}

然后在序列化时注册这个转换器：

var options = new JsonSerializerOptions();
options.Converters.Add(new LegacyKeyValuePairConverter<int, int>());

总结

.NET 5 对 KeyValuePair<TKey, TValue> 序列化行为的改进使其更加符合开发者的预期，与其他类型的处理方式保持一致。这一变更虽然可能影响现有代码，但提供了更好的灵活性和一致性。开发者应该评估这一变更对现有系统的影响，并采取适当的迁移策略。