简介
Newtonsoft.Json是一个在.NET环境下开源的JSON格式序列化和反序列化的类库。它可以将.NET对象转换为JSON格式的字符串，也可以将JSON格式的字符串转换为.NET对象。这个类库在.NET开发中被广泛使用，因为它功能强大、易于使用，并且有良好的性能。
使用Newtonsoft.Json，你可以方便地进行以下操作：
- 序列化：将.NET对象转换为JSON字符串。这通常用于将数据发送到Web服务或保存到文件。
- 反序列化：将JSON字符串转换为.NET对象。这通常用于从Web服务接收数据或从文件中读取数据。
- JSON数据的操作：Newtonsoft.Json提供了丰富的API，允许你对JSON数据进行各种操作，如修改、查询、添加和删除等。
要使用Newtonsoft.Json，你首先需要将其添加到你的项目中。你可以通过NuGet包管理器来安装它。一旦安装完成，你就可以在你的代码中使用它。
官网：https://www.newtonsoft.com/json/help/html/Introduction.htm
序列化属性
https://www.newtonsoft.com/json/help/html/SerializationSettings.htm
Converters: 一个包含自定义转换器的集合，这些转换器用于将对象序列化为 JSON 或从 JSON 反序列化为对象。
DateFormatHandling: 控制日期和时间格式的处理方式。例如，可以将日期格式化为特定的字符串格式，或者使用 ISO 8601 格式。
DateTimeZoneHandling: 控制日期时间值的时区处理方式。可以选择本地、UTC 或不处理。
IsoDateTimeFormat: 一个布尔值，用于指示是否将日期时间值格式化为 ISO 8601 格式。
SerializationMemberSelector: 一个委托，允许您自定义哪些属性将被序列化。
ReferenceLoopHandling: 控制循环引用的处理方式。可以选择忽略、警告或抛出异常。
MissingMemberHandling: 控制缺少成员的处理方式。可以选择忽略、抛出异常或引发警告。
DefaultSettings: 使用默认设置进行序列化。这些设置可以覆盖应用程序中的其他特定设置。
ContractResolver: 用于控制 JSON.NET 如何推断和创建 JSON 合同。这允许您自定义命名约定、忽略默认属性等。
NamingStrategy: 用于控制 JSON.NET 中的命名约定。例如，可以使用 CamelCase 或 PascalCase 命名约定。
StringEscapeHandling: 控制字符串转义字符的处理方式。可以选择逃逸或不逃逸转义字符。
ReferenceResolutionPolicy: 控制如何处理重复引用相同的对象。可以选择警告、忽略或抛出异常。
NullValueHandling: 控制如何处理空值。可以选择忽略、表示为 null 或使用默认值。
序列化特性
- JsonObjectAttribute - 放置在类上以控制如何将它们序列化为 JSON 对象。
- JsonArrayAttribute - 放置在集合上以控制如何将它们序列化为 JSON 数组。
- JsonDictionaryAttribute - 放置在字典上以控制如何将它们序列化为 JSON 对象。
- JsonPropertyAttribute - 放置在字段和属性上，以控制如何将它们序列化为 JSON 对象中的属性。
- JsonConverterAttribute - 放置在类或字段和属性上，以指定序列化期间应使用哪个 JsonConverter。
- JsonExtensionDataAttribute - 放置在集合字段或属性上，用于将没有匹配类成员的属性反序列化到指定的集合中，并在序列化期间写入值。
- JsonConstructorAttribute - 放置在构造函数上以指定应在反序列化期间使用它来创建类。
LINQ To JSON
NQ to JSON 是用于处理 JSON 对象的 API。它在设计时考虑了 LINQ，可以快速查询和创建 JSON 对象。LINQ to JSON 位于 Newtonsoft.Json.Linq 命名空间下。
JObject o = JObject.Parse(@"{'CPU': 'Intel','Drives': ['DVD read/writer','500 gigabyte hard drive']
}");string cpu = (string)o["CPU"];
// Intelstring firstDrive = (string)o["Drives"][0];
// DVD read/writerIList<string> allDrives = o["Drives"].Select(t => (string)t).ToList();
性能技巧
- 重用合约解析器
- 优化内存使用
- Json转换器
- 手动序列化
- 基准测试
对比 System.Text.Json
https://learn.microsoft.com/zh-cn/dotnet/standard/serialization/system-text-json/migrate-from-newtonsoft?pivots=dotnet-8-0#table-of-differences
| Newtonsoft.Json 功能 | System.Text.Json 等效 |
|---|---|
| 默认情况下不区分大小写的反序列化 | ✔️ PropertyNameCaseInsensitive 全局设置 |
| Camel 大小写属性名称 | ✔️ PropertyNamingPolicy 全局设置 |
| 对属性名称采用蛇形命名法 | ✔️ 蛇形命名法命名策略 |
| 最小字符转义 | ✔️ 严格字符转义，可配置 |
NullValueHandling.Ignore 全局设置 | ✔️ DefaultIgnoreCondition 全局选项 |
| 允许注释 | ✔️ ReadCommentHandling 全局设置 |
| 允许尾随逗号 | ✔️ AllowTrailingCommas 全局设置 |
| 自定义转换器注册 | ✔️ 优先级顺序不同 |
| 默认情况下无最大深度 | ✔️ 默认最大深度为 64，可配置 |
PreserveReferencesHandling 全局设置 | ✔️ ReferenceHandling 全局设置 |
| 序列化或反序列化带引号的数字 | ✔️ [NumberHandling 全局设置，JsonNumberHandling] 特性 |
| 反序列化为不可变类和结构 | ✔️ JsonConstructor，C# 9 记录 |
| 支持字段 | ✔️ [IncludeFields 全局设置，JsonInclude] 特性 |
DefaultValueHandling 全局设置 | ✔️ DefaultIgnoreCondition 全局设置 |
[JsonProperty] 上的 NullValueHandling 设置 | ✔️ JsonIgnore 特性 |
[JsonProperty] 上的 DefaultValueHandling 设置 | ✔️ JsonIgnore 特性 |
反序列化具有非字符串键的 Dictionary | ✔️ 受支持 |
| 支持非公共属性资源库和 Getter | ✔️ JsonInclude 特性 |
[JsonConstructor] 特性 | ✔️ [JsonConstructor] 特性 |
ReferenceLoopHandling 全局设置 | ✔️ ReferenceHandling 全局设置 |
| 回调 | ✔️ 回调 |
| NaN、Infinity、-Infinity | ✔️ 受支持 |
[JsonProperty] 特性上的 Required 设置 | ✔️ [JsonRequired] 特性和 C# 必需的修饰符 |
DefaultContractResolver 用于忽略属性 | ✔️ DefaultJsonTypeInfoResolver 类 |
| 多态序列化 | ✔️ [JsonDerivedType] 特性 |
| 多态反序列化 | ✔️ [JsonDerivedType] 特性上的类型鉴别器 |
| 反序列化字符串枚举值 | ✔️ 反序列化字符串枚举值 |
MissingMemberHandling 全局设置 | ✔️ 处理缺少的成员 |
| 在没有资源库的情况下填充属性 | ✔️ 在没有资源库的情况下填充属性 |
ObjectCreationHandling 全局设置 | ✔️ 重用而不是替换属性 |
| 支持范围广泛的类型 | ⚠️ ⚠ |
将推断类型反序列化为 object 属性 | ⚠️ ⚠ |
将 JSON null 文本反序列化为不可为 null 的值类型 | ⚠️ ⚠ |
DateTimeZoneHandling、DateFormatString 设置 | ⚠️ ⚠ |
JsonConvert.PopulateObject 方法 | ⚠️ ⚠ |
支持 System.Runtime.Serialization 特性 | ⚠️ ⚠ |
JsonObjectAttribute | ⚠️ ⚠ |
| 允许不带引号的属性名称 | ❌设计上不受支持 |
| 字符串值前后允许单引号 | ❌设计上不受支持 |
| 对字符串属性允许非字符串 JSON 值 | ❌设计上不受支持 |
TypeNameHandling.All 全局设置 | ❌设计上不受支持 |
支持 JsonPath 查询 | ❌不支持 |
| 可配置的限制 | ❌不支持 |
封装 JsonHelper 帮助类
/// <summary>/// Json序列化反序列化类/// </summary>public class JsonHelper{private static readonly JsonSerializerSettings _jsonSerializerSettings;static JsonHelper(){_jsonSerializerSettings = DefaultSerializerSettings;}private static JsonSerializerSettings DefaultSerializerSettings{get{var settings = new JsonSerializerSettings();// 设置如何将日期写入JSON文本。默认值为“IsoDateFormat”//settings.DateFormatHandling = DateFormatHandling.IsoDateFormat;// 设置在序列化和反序列化期间如何处理DateTime时区。默认值为 “RoundtripKind”//settings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind;// 设置在序列化和反序列化期间如何处理默认值。默认值为“Include”//settings.DefaultValueHandling = DefaultValueHandling.Include;// 设置写入JSON文本时DateTime和DateTimeOffset值的格式，以及读取JSON文本时预期的日期格式。默认值为“ yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK ”。settings.DateFormatString = "yyyy-MM-dd HH:mm:ss";// 设置在序列化和反序列化期间如何处理空值。默认值为“Include”//settings.NullValueHandling = NullValueHandling.Include;// 设置序列化程序在将.net对象序列化为JSON时使用的契约解析器settings.ContractResolver = new CamelCasePropertyNamesContractResolver();// 设置如何处理引用循环(例如，类引用自身)。默认值为“Error”。settings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;// 是否格式化文本settings.Formatting = Formatting.Indented;//支持将Enum 由默认 Number类型 转换为String//settings.SerializerSettings.Converters.Add(new StringEnumConverter());//将long类型转为stringsettings.SerializerSettings.Converters.Add(new NumberConverter(NumberConverterShip.Int64));return settings;}}public static T Deserialize<T>(string json, JsonSerializerSettings serializerSettings = null){if (string.IsNullOrEmpty(json)) return default;if (serializerSettings == null) serializerSettings = _jsonSerializerSettings;//值类型和String类型if (typeof(T).IsValueType || typeof(T) == typeof(string)){return (T)Convert.ChangeType(json, typeof(T));}return JsonConvert.DeserializeObject<T>(json, serializerSettings);}public static string Serialize<T>(T obj, JsonSerializerSettings serializerSettings = null){if (obj is null) return string.Empty;if (obj is string) return obj.ToString();if (serializerSettings == null) serializerSettings = _jsonSerializerSettings;return JsonConvert.SerializeObject(obj, serializerSettings);}}
全局配置 Newtonsoft.Json
public static class JsonSerializeExtensions{public static IMvcBuilder AddMCodeJsonOptions(this IMvcBuilder builder, Action<MvcNewtonsoftJsonOptions> configure = null){/**/builder.AddNewtonsoftJson(options =>{// 设置如何将日期写入JSON文本。默认值为“IsoDateFormat”//options.SerializerSettings.DateFormatHandling = DateFormatHandling.IsoDateFormat;// 设置在序列化和反序列化期间如何处理DateTime时区。默认值为 “RoundtripKind”//options.SerializerSettings.DateTimeZoneHandling = DateTimeZoneHandling.RoundtripKind;// 设置在序列化和反序列化期间如何处理默认值。默认值为“Include”//options.SerializerSettings.DefaultValueHandling = DefaultValueHandling.Include;// 设置写入JSON文本时DateTime和DateTimeOffset值的格式，以及读取JSON文本时预期的日期格式。默认值为“ yyyy'-'MM'-'dd'T'HH':'mm':'ss.FFFFFFFK ”。options.SerializerSettings.DateFormatString = "yyyy-MM-dd HH:mm:ss";// 设置在序列化和反序列化期间如何处理空值。默认值为“Include”//options.SerializerSettings.NullValueHandling = NullValueHandling.Include;// 设置序列化程序在将.net对象序列化为JSON时使用的契约解析器options.SerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();// 设置如何处理引用循环(例如，类引用自身)。默认值为“Error”。options.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore;// 是否格式化文本options.SerializerSettings.Formatting = Formatting.Indented;//将long类型转为stringoptions.SerializerSettings.Converters.Add(new NumberConverter(NumberConverterShip.Int64));configure.Invoke(options);});return builder;}}
