簡介
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"];
// Intel
string firstDrive = (string)o["Drives"][0];
// DVD read/writer
IList<string> allDrives = o["Drives"].Select(t => (string)t).ToList();
性能技巧
對比 System.Text.Json
| 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類型轉爲string
settings.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類型轉爲string
options.SerializerSettings.Converters.Add(new NumberConverter(NumberConverterShip.Int64));
configure.Invoke(options);
});
return builder;
}
}