ToB企服应用市场:ToB评测及商务社交产业平台

标题: 从 Newtonsoft.Json 迁移到 System.Text.Json [打印本页]
作者: 张春    时间: 2023-2-14 14:13
标题: 从 Newtonsoft.Json 迁移到 System.Text.Json
一.写在前面

System.Text.Json 是 .NET Core 3 及以上版本内置的 Json 序列化组件，刚推出的时候经常看到踩各种坑的吐槽，现在经过几个版本的迭代优化，提升了易用性，修复了各种问题，是时候考虑使用 System.Text.Json 了。本文将从使用层面来进行对比。
System.Text.Json 在默认情况下十分严格，避免进行任何猜测或解释，强调确定性行为。比如：字符串默认转义，默认不允许尾随逗号，默认不允许带引号的数字等，不允许单引号或者不带引号的属性名称和字符串值。 该库是为了实现性能和安全性而特意这样设计的。Newtonsoft.Json 默认情况下十分灵活。
关于性能，参考 Incerry 的性能测试：.NET性能系列文章二：Newtonsoft.Json vs. System.Text.Json，如果打算使用 .NET 7 不妨考虑一下 System.Text.Json。
Newtonsoft.Json 使用 13.0.2 版本，基于 .NET 7。
二.序列化

1.序列化

定义 Class
  1. public class Cat
  2. {
  3.     public string? Name { get; set; }
  4.     public int Age { get; set; }
  5. }
复制代码
序列化
  1. var cat = new Cat() { Name = "xiaoshi", Age = 18 };
  3. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
  4. // output: {"Name":"xiaoshi","Age":18}
  5. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
  6. // output: {"Name":"xiaoshi","Age":18}
复制代码
变化：JsonConvert.SerializeObject()->JsonSerializer.Serialize()
2.忽略属性

2.1 通用
  1. [Newtonsoft.Json.JsonIgnore]
  2. [System.Text.Json.Serialization.JsonIgnore]
  3. public int Age { get; set; }
复制代码
输出：
  1. var cat = new Cat() { Name = "xiaoshi", Age = 18 };
  3. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
  4. // output: {"Name":"xiaoshi"}
  5. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
  6. // output: {"Name":"xiaoshi"}
复制代码
变化：无
2.2 忽略所有只读属性

代码：
  1. public class Cat
  2. {
  3.     public string? Name { get; set; }
  4.    
  5.     public int Age { get;  }
  7.     public Cat(int age)
  8.     {
  9.         Age = age;
  10.     }
  11. }
  13. var cat = new Cat(18) { Name = "xiaoshi"};
  14. var options = new System.Text.Json.JsonSerializerOptions
  15. {
  16.     IgnoreReadOnlyProperties = true,
  17. };
  18. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  19. // output: {"Name":"xiaoshi"}
复制代码
Newtonsoft.Json 需要自定义 ContractResolver 才能实现：https://stackoverflow.com/questions/45010583
2.3 忽略所有 null 属性

代码：
  1. var cat = new Cat() { Name = null,Age = 18};
  3. var op = new Newtonsoft.Json.JsonSerializerSettings()
  4. {
  5.     NullValueHandling =NullValueHandling.Ignore
  6. };
  8. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  9. // output: {"Name":"xiaoshi"}
  12. var options = new System.Text.Json.JsonSerializerOptions
  13. {
  14.     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
  15. };
  16. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  17. // output: {"Name":"xiaoshi"}
复制代码
默认情况下两者都是不忽略的，需要自行设置
2.4 忽略所有默认值属性

代码：
  1. var cat = new Cat() { Name = "xiaoshi",Age = 0};
  3. var op = new Newtonsoft.Json.JsonSerializerSettings()
  4. {
  5.     DefaultValueHandling = DefaultValueHandling.Ignore
  6. };
  8. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  9. // output: {"Name":"xiaoshi"}
  12. var options = new System.Text.Json.JsonSerializerOptions
  13. {
  14.     DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
  15. };
  16. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  17. // output: {"Name":"xiaoshi"}
复制代码
不管是引用类型还是值类型都具有默认值，引用类型为 null，int 类型为 0。
两者都支持此功能。
3.大小写

默认情况下两者序列化都是 Pascal 命名，及首字母大写，在 JavaScript 以及 Java 等语言中默认是使用驼峰命名，所以在实际业务中是离不开使用驼峰的。
代码：
  1. var cat = new Cat() { Name = "xiaoshi",Age = 0};
  3. var op = new Newtonsoft.Json.JsonSerializerSettings()
  4. {
  5.     ContractResolver = new CamelCasePropertyNamesContractResolver()
  6. };
  8. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  9. // output: {"name":"xiaoshi","age":0}
  12. var options = new System.Text.Json.JsonSerializerOptions
  13. {
  14.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  15. };
  16. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  17. // output: {"name":"xiaoshi","age":0}
复制代码
4.字符串转义

System.Text.Json 默认会对非 ASCII 字符进行转义，会将它们替换为 \uxxxx，其中 xxxx 为字符的 Unicode 代码。这是为了安全而考虑（XSS 攻击等），会执行严格的字符转义。而 Newtonsoft.Json 默认则不会转义。
默认：
  1. var cat = new Cat() { Name = "小时",Age = 0};
  3. var op = new Newtonsoft.Json.JsonSerializerSettings()
  4. {
  5.     ContractResolver = new CamelCasePropertyNamesContractResolver()
  6. };
  8. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  9. // output: {"name":"小时","age":0}
  12. var options = new System.Text.Json.JsonSerializerOptions
  13. {
  14.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  15. };
  16. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  17. // output: {"name":"\u5C0F\u65F6","age":0}
复制代码
System.Text.Json 关闭转义：
  1. var options = new System.Text.Json.JsonSerializerOptions
  2. {
  3.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  4.     Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
  5. };
  6. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  7. // output: {"name":"小时","age":0}
复制代码
Newtonsoft.Json 开启转义：
  1. var op = new Newtonsoft.Json.JsonSerializerSettings()
  2. {
  3.     ContractResolver = new CamelCasePropertyNamesContractResolver(),
  4.     StringEscapeHandling = StringEscapeHandling.EscapeNonAscii
  5. };
  7. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  8. // output: {"name":"\u5c0f\u65f6","age":0}
复制代码
详细说明：如何使用 System.Text.Json 自定义字符编码
5.自定义转换器

自定义转换器 Converter，是我们比较常用的功能，以自定义 Converter 来输出特定的日期格式为例。
Newtonsoft.Json:
  1. public class CustomDateTimeConverter : IsoDateTimeConverter
  2. {
  3.     public CustomDateTimeConverter()
  4.     {
  5.         DateTimeFormat = "yyyy-MM-dd";
  6.     }
  8.     public CustomDateTimeConverter(string format)
  9.     {
  10.         DateTimeFormat = format;
  11.     }
  12. }
  14. // test
  15. var op = new Newtonsoft.Json.JsonSerializerSettings()
  16. {
  17.     ContractResolver = new CamelCasePropertyNamesContractResolver(),
  18.     Converters = new List<JsonConverter>() { new CustomDateTimeConverter() }
  19. };
  21. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  22. // output: {"name":"xiaoshi","now":"2023-02-13","age":0}
复制代码
System.Text.Json:
  1. public class CustomDateTimeConverter : JsonConverter<DateTime>
  2. {
  3.     public override DateTime Read(
  4.         ref Utf8JsonReader reader,
  5.         Type typeToConvert,
  6.         JsonSerializerOptions options) =>
  7.         DateTime.ParseExact(reader.GetString()!,
  8.             "yyyy-MM-dd", CultureInfo.InvariantCulture);
  10.     public override void Write(
  11.         Utf8JsonWriter writer,
  12.         DateTime dateTimeValue,
  13.         JsonSerializerOptions options) =>
  14.         writer.WriteStringValue(dateTimeValue.ToString(
  15.             "yyyy-MM-dd", CultureInfo.InvariantCulture));
  16. }
  18. // test
  19. var options = new System.Text.Json.JsonSerializerOptions
  20. {
  21.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  22.     Converters = { new CustomDateTimeConverter() }
  23. };
  24. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  25. // output: {"name":"xiaoshi","age":0,"now":"2023-02-13"}
复制代码
两者的使用方法都是差不多的，只是注册优先级有所不同。
Newtonsoft.Json：属性上的特性>类型上的特性>Converters 集合
System.Text.Json：属性上的特性>Converters 集合>类型上的特性
官方文档：如何编写用于 JSON 序列化的自定义转换器
6.循环引用

有如下定义：
  1. public class Cat
  2. {
  4.     public string? Name { get; set; }
  6.     public int Age { get; set; }
  7.    
  8.     public Cat Child { get; set; }
  9.    
  10.     public Cat Parent { get; set; }
  11. }
  13. var cat1 = new Cat() { Name = "xiaoshi",Age = 0};
  14. var cat2 = new Cat() { Name = "xiaomao",Age = 0};
  16. cat1.Child = cat2;
  17. cat2.Parent = cat1;
复制代码
序列化 cat1 默认两者都会抛出异常，如何解决？
Newtonsoft.Json：
  1. var op = new Newtonsoft.Json.JsonSerializerSettings()
  2. {
  3.     ContractResolver = new CamelCasePropertyNamesContractResolver(),
  4.     ReferenceLoopHandling = ReferenceLoopHandling.Ignore,
  5. };
  7. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat1,op));
复制代码
设置 ReferenceLoopHandling.Ignore 即可。
System.Text.Json：
  1. var options = new System.Text.Json.JsonSerializerOptions
  2. {
  3.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  4.     ReferenceHandler = ReferenceHandler.IgnoreCycles
  5. };
  6. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat1, options));
复制代码
等效设置
System.Text.JsonNewtonsoft.JsonReferenceHandler = ReferenceHandler.PreservePreserveReferencesHandling=PreserveReferencesHandling.AllReferenceHandler = ReferenceHandler.IgnoreCyclesReferenceLoopHandling = ReferenceLoopHandling.Ignore
详细说明：如何在 System.Text.Json 中保留引用
8.支持字段(Field)

在序列化和反序列时支持字段，字段不能定义为 private。
  1. public class Cat
  2. {
  4.     public string? Name { get; set; }
  6.     public int _age;
  8.     public Cat()
  9.     {
  10.         _age = 13;
  11.     }
  12. }
  14. var op = new Newtonsoft.Json.JsonSerializerSettings()
  15. {
  16.     ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
  17. };
  19. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  20. // output: {"_age":13,"name":"xiaoshi"}
  22. var options = new System.Text.Json.JsonSerializerOptions
  23. {
  24.     PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
  25.     IncludeFields = true // 或者 JsonIncludeAttribute
  26. };
  29. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  30. // output: {"name":"xiaoshi","_age":13}
复制代码
System.Text.Json 默认不支持直接序列化和反序列化字段，需要设置 IncludeFields = true或者 JsonIncludeAttribute 特性。
8.顺序

自定义属性在 Json 输出中的顺序：
  1. public class Cat
  2. {
  4.     public string? Name { get; set; }
  6.     [System.Text.Json.Serialization.JsonPropertyOrder(0)]
  7.     [Newtonsoft.Json.JsonProperty(Order = 0)]
  8.     public int Age { get; set; }
  9. }
复制代码
System.Text.Json 使用 JsonPropertyOrder，Newtonsoft.Json 使用 JsonProperty(Order)
9.字节数组

Newtonsoft.Json 不支持直接序列化为字节数组，System.Text.Json 支持直接序列化为 UTF-8 字节数组。
System.Text.Json：
  1. var bytes = JsonSerializer.SerializeToUtf8Bytes(cat)
复制代码
序列化为 UTF-8 字节数组比使用基于字符串的方法大约快 5-10%。
10.重命名
  1. public class Cat
  2. {
  4.     public string? Name { get; set; }
  6.     [System.Text.Json.Serialization.JsonPropertyName("catAge")]
  7.     [Newtonsoft.Json.JsonProperty("catAge")]
  8.     public int Age { get; set; }
  9. }
复制代码
重命名 Json 属性名称，System.Text.Json 使用 JsonPropertyName，Newtonsoft.Json 使用 JsonProperty。
11.缩进

Newtonsoft.Json：
  1. var op = new Newtonsoft.Json.JsonSerializerSettings()
  2. {
  3.     ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
  4.     // this option
  5.     Formatting = Newtonsoft.Json.Formatting.Indented,
  6. };
  8. Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
  9. // output:
  10. // {
  11. //     "name": "xiaoshi",
  12. //     "catAge": 0
  13. // }
复制代码
System.Text.Json
  1. var options = new System.Text.Json.JsonSerializerOptions
  2. {
  3.     PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
  4.     // this option
  5.     WriteIndented = true,
  6. };
  9. Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
  10. // output:
  11. // {
  12. //     "name": "xiaoshi",
  13. //     "catAge": 0
  14. // }
复制代码
三.反序列化

1.反序列化

定义：
  1. public class Cat
  2. {
  3.     public string? Name { get; set; }
  4.     public int Age { get; set; }
  5. }var json = """{"name":"xiaoshi","age":16} """;Cat cat;
复制代码
Newtonsoft.Json：
  1. var op = new Newtonsoft.Json.JsonSerializerSettings()
  2. {
  3.     ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
  4. };
  6. cat=Newtonsoft.Json.JsonConvert.DeserializeObject<Cat>(json, op);
  8. Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
  9. // output: CatName xiaoshi, Age 16
复制代码
System.Text.Json：
  1. var options = new System.Text.Json.JsonSerializerOptions
  2. {
  3.     PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
  4. };
  6. cat=System.Text.Json.JsonSerializer.Deserialize<Cat>(json,options);
  8. Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
  9. // output: CatName xiaoshi, Age 16
复制代码
变化 JsonConvert.DeserializeObject->JsonSerializer.Deserialize
2.允许注释

在反序列化过程中，Newtonsoft.Json 在默认情况下会忽略 JSON 中的注释。 System.Text.Json 默认是对注释引发异常，因为 System.Text.Json 规范不包含它们。
  1. var json = """
  2. {
  3.     "name": "xiaoshi", // cat name
  4.     "age": 16
  5. }
  6. """;
  7. Cat cat;
  9. var options = new System.Text.Json.JsonSerializerOptions
  10. {
  11.     PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
  12.     // 不设置会引发异常
  13.     ReadCommentHandling = System.Text.Json.JsonCommentHandling.Skip,
  14. };
  16. cat=System.Text.Json.JsonSerializer.Deserialize<Cat>(json,options);
  18. Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
  19. // output: CatName xiaoshi, Age 16
复制代码
设置 ReadCommentHandling=JsonCommentHandling.Skip即可忽略注释。
详细说明：如何使用 System.Text.Json 支持某种无效的 JSON
3.尾随逗号

尾随逗号即 Json 末尾为逗号：
无尾随逗号：
  1. {
  2.     "name": "xiaoshi",
  3.     "age": 16
  4. }
复制代码
有尾随逗号：
  1. {
  2.     "name": "xiaoshi",
  3.     "age": 16,
  4. }
复制代码
System.Text.Json 默认对尾随逗号引发异常，可以通过 AllowTrailingCommas = true 来设置
  1. var json = """{
  2.     "name": "xiaoshi",
  3.     "age": 16,
  4. }"""; Cat cat;  var options = new System.Text.Json.JsonSerializerOptions{    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,    AllowTrailingCommas = true,};cat=System.Text.Json.JsonSerializer.Deserialize(json,options);Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");// output: CatName xiaoshi, Age 16
复制代码
尾随逗号一般和允许注释一起使用，因为行注释必须写在引号以后。
4.带引号数字

在标准 Json 里，数字类型是不带引号的，如：{"Name":"xiaoshi","Age":18}，但有时我们可能会遇到不标准的异类，Newtonsoft.Json 默认是支持直接反序列化为数字类型的，而 System.Text.Json 基于严格的标准出发，默认不支持，但是可配置。
  1. var options = new System.Text.Json.JsonSerializerOptions
  2. {
  3.     PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
  4.     NumberHandling = JsonNumberHandling.AllowReadingFromString
  5. };
  7. // C# 11 原始字符串
  8. var json="""{"name":"xiaoshi","age":"13"}""";
  10. Console.WriteLine(System.Text.Json.JsonSerializer.Deserialize<Cat>(json, options).Age);
  11. // output: 13
复制代码
设置 NumberHandling = JsonNumberHandling.AllowReadingFromString 即可。
5.Json DOM

不直接反序列化为对象，比如 Newtonsoft.Json 里的 JObject.Parse。在 System.Text.Json 里可以使用 JsonNode、JsonDocument、JsonObject 等。
详细说明：如何在 System.Text.Json 中使用 JSON DOM、Utf8JsonReader 和 Utf8JsonWriter
6.JsonConstructor

通过 JsonConstructor 特性指定使用的反序列化构造方法，两者是一致的。
四.无法满足的场景

官方给出了对比 Newtonsoft.Json 没有直接支持的功能，但是可以通过自定义 Converter 来支持。如果需要依赖这部分功能，那么在迁移过程中需要进行代码更改。
Newtonsoft.JsonSystem.Text.Json支持范围广泛的类型⚠️ ⚠将推断类型反序列化为 object 属性⚠️ ⚠将 JSON null 文本反序列化为不可为 null 的值类型⚠️ ⚠DateTimeZoneHandling、DateFormatString 设置⚠️ ⚠JsonConvert.PopulateObject 方法⚠️ ⚠ObjectCreationHandling 全局设置⚠️ ⚠在不带 setter 的情况下添加到集合⚠️ ⚠对属性名称采用蛇形命名法⚠️ ⚠以下功能 System.Text.Json 不支持：
Newtonsoft.JsonSystem.Text.Json支持 System.Runtime.Serialization 特性❌❌MissingMemberHandling 全局设置❌❌允许不带引号的属性名称❌❌字符串值前后允许单引号❌❌对字符串属性允许非字符串 JSON 值❌❌TypeNameHandling.All 全局设置❌❌支持 JsonPath 查询❌❌可配置的限制❌❌五.结束

在 Ms Learn(Docs) 和 Google 之间频繁切换写完了这篇文章，希望对大家在从 Newtonsoft.Json 迁移到 System.Text.Json 有所帮助。就我个人而言我是打算使用 System.Text.Json 了。
参考资料


免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！



欢迎光临 ToB企服应用市场:ToB评测及商务社交产业平台 (https://dis.qidao123.com/) Powered by Discuz! X3.4