使用Newtonsoft.JSON序列化JSON配置文件时如何保留现有条目？

方法一：使用JsonExtensionData特性（官方推荐） #

Newtonsoft.Json原生提供了[JsonExtensionData]特性，专门用来处理反序列化时的未知字段——它会自动将未匹配到类属性的JSON键值对存入指定字典，序列化时再原样输出，无需手动额外处理。

代码示例 #

定义设置类时，添加带该特性的字典属性：

public class AppSettings
{
    // 当前版本识别的已知属性
    public string Theme { get; set; }
    public int WindowWidth { get; set; }

    // 自动存储所有未知JSON条目
    [JsonExtensionData]
    private Dictionary<string, JToken> _unrecognizedSettings;
}

工作逻辑 #

1. 反序列化设置文件时，所有未匹配到类属性的字段会自动存入_unrecognizedSettings
2. 修改已知属性后，序列化对象时，_unrecognizedSettings中的内容会被完整写回JSON文件
3. 最终实现：仅更新当前版本识别的字段，完全保留新旧版本的未知条目

方法二：手动合并JSON对象（精细控制场景） #

如果需要自定义未知字段的处理逻辑（比如过滤特定字段、做版本兼容转换），可以直接操作JObject实现增量更新：

代码示例 #

// 1. 读取原始JSON文件内容
var originalJson = File.ReadAllText("settings.json");
var originalJObj = JObject.Parse(originalJson);

// 2. 反序列化为设置对象进行修改
var settings = originalJObj.ToObject<AppSettings>();
settings.Theme = "DarkMode"; // 更新已知属性

// 3. 将修改后的对象转为JObject
var updatedJObj = JObject.FromObject(settings);

// 4. 把原始JSON中的未知字段合并到更新后的对象中
foreach (var prop in originalJObj.Properties())
{
    if (!updatedJObj.ContainsKey(prop.Name))
    {
        updatedJObj.Add(prop.Name, prop.Value);
    }
}

// 5. 保存回文件
File.WriteAllText("settings.json", updatedJObj.ToString(Formatting.Indented));

这种方式的核心是基于原始JSON做增量覆盖，只更新当前版本识别的字段，完全保留原始文件中的所有未知内容。

最佳实践 #

• 优先用JsonExtensionData：官方原生支持，代码简洁，维护成本最低
• 给设置文件加版本号：在设置类中添加int SettingsVersion { get; set; }字段，后续版本迭代时可根据版本号做针对性迁移（比如旧字段映射、数据格式转换）
• 向后兼容过渡：移除旧字段前，先标记为[Obsolete]并保留3-5个版本，给用户足够的过渡时间
• 禁止直接覆盖：永远基于原始设置文件做增量更新，不要直接序列化对象覆盖整个文件

内容的提问来源于stack exchange，提问作者J. Meyer