從 Newtonsoft.Json 遷移到 System.Text.Json

曉晨Master發表於2023-02-14

一.寫在前面

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

public class Cat
{
    public string? Name { get; set; }
    public int Age { get; set; }
}

序列化

var cat = new Cat() { Name = "xiaoshi", Age = 18 };

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
// output: {"Name":"xiaoshi","Age":18}
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
// output: {"Name":"xiaoshi","Age":18}

變化：JsonConvert.SerializeObject()->JsonSerializer.Serialize()

2.忽略屬性

2.1 通用

[Newtonsoft.Json.JsonIgnore]
[System.Text.Json.Serialization.JsonIgnore]
public int Age { get; set; }

輸出：

var cat = new Cat() { Name = "xiaoshi", Age = 18 };

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat));
// output: {"Name":"xiaoshi"}
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat));
// output: {"Name":"xiaoshi"}

變化：無

2.2 忽略所有隻讀屬性

程式碼：

public class Cat
{
    public string? Name { get; set; }
    
    public int Age { get;  }

    public Cat(int age)
    {
        Age = age;
    }
}

var cat = new Cat(18) { Name = "xiaoshi"};
var options = new System.Text.Json.JsonSerializerOptions
{
    IgnoreReadOnlyProperties = true,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

Newtonsoft.Json 需要自定義 ContractResolver 才能實現：https://stackoverflow.com/questions/45010583

2.3 忽略所有 null 屬性

程式碼：

var cat = new Cat() { Name = null,Age = 18};

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    NullValueHandling =NullValueHandling.Ignore
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"Name":"xiaoshi"}


var options = new System.Text.Json.JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

預設情況下兩者都是不忽略的，需要自行設定

2.4 忽略所有預設值屬性

程式碼：

var cat = new Cat() { Name = "xiaoshi",Age = 0};

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    DefaultValueHandling = DefaultValueHandling.Ignore
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"Name":"xiaoshi"}


var options = new System.Text.Json.JsonSerializerOptions
{
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"Name":"xiaoshi"}

不管是引用型別還是值型別都具有預設值，引用型別為 null，int 型別為 0。

兩者都支援此功能。

3.大小寫

預設情況下兩者序列化都是 Pascal 命名，及首字母大寫，在 JavaScript 以及 Java 等語言中預設是使用駝峰命名，所以在實際業務中是離不開使用駝峰的。

程式碼：

var cat = new Cat() { Name = "xiaoshi",Age = 0};

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver()
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"xiaoshi","age":0}


var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"xiaoshi","age":0}

4.字串轉義

System.Text.Json 預設會對非 ASCII 字元進行轉義，會將它們替換為 \uxxxx，其中 xxxx 為字元的 Unicode 程式碼。這是為了安全而考慮（XSS 攻擊等），會執行嚴格的字元轉義。而 Newtonsoft.Json 預設則不會轉義。

預設：

var cat = new Cat() { Name = "小時",Age = 0};

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver()
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"小時","age":0}


var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"\u5C0F\u65F6","age":0}

System.Text.Json 關閉轉義：

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping,
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"小時","age":0}

Newtonsoft.Json 開啟轉義：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    StringEscapeHandling = StringEscapeHandling.EscapeNonAscii
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"\u5c0f\u65f6","age":0}

詳細說明：如何使用 System.Text.Json 自定義字元編碼

5.自定義轉換器

自定義轉換器 Converter，是我們比較常用的功能，以自定義 Converter 來輸出特定的日期格式為例。

Newtonsoft.Json:

public class CustomDateTimeConverter : IsoDateTimeConverter
{
    public CustomDateTimeConverter()
    {
        DateTimeFormat = "yyyy-MM-dd";
    }

    public CustomDateTimeConverter(string format)
    {
        DateTimeFormat = format;
    }
}

// test
var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    Converters = new List<JsonConverter>() { new CustomDateTimeConverter() }
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"name":"xiaoshi","now":"2023-02-13","age":0}

System.Text.Json:

public class CustomDateTimeConverter : JsonConverter<DateTime>
{
    public override DateTime Read(
        ref Utf8JsonReader reader,
        Type typeToConvert,
        JsonSerializerOptions options) =>
        DateTime.ParseExact(reader.GetString()!,
            "yyyy-MM-dd", CultureInfo.InvariantCulture);

    public override void Write(
        Utf8JsonWriter writer,
        DateTime dateTimeValue,
        JsonSerializerOptions options) =>
        writer.WriteStringValue(dateTimeValue.ToString(
            "yyyy-MM-dd", CultureInfo.InvariantCulture));
}

// test
var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    Converters = { new CustomDateTimeConverter() }
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"xiaoshi","age":0,"now":"2023-02-13"}

兩者的使用方法都是差不多的，只是註冊優先順序有所不同。

Newtonsoft.Json：屬性上的特性>型別上的特性>Converters 集合

System.Text.Json：屬性上的特性>Converters 集合>型別上的特性

官方文件：如何編寫用於 JSON 序列化的自定義轉換器

6.迴圈引用

有如下定義：

public class Cat
{

    public string? Name { get; set; }

    public int Age { get; set; }
    
    public Cat Child { get; set; }
    
    public Cat Parent { get; set; }
}

var cat1 = new Cat() { Name = "xiaoshi",Age = 0};
var cat2 = new Cat() { Name = "xiaomao",Age = 0};

cat1.Child = cat2;
cat2.Parent = cat1;

序列化 cat1 預設兩者都會丟擲異常，如何解決？

Newtonsoft.Json：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new CamelCasePropertyNamesContractResolver(),
    ReferenceLoopHandling = ReferenceLoopHandling.Ignore,
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat1,op));

設定 ReferenceLoopHandling.Ignore 即可。

System.Text.Json：

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    ReferenceHandler = ReferenceHandler.IgnoreCycles
};
Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat1, options));

等效設定

System.Text.Json	Newtonsoft.Json
ReferenceHandler = ReferenceHandler.Preserve	PreserveReferencesHandling`=`PreserveReferencesHandling.All
ReferenceHandler = ReferenceHandler.IgnoreCycles	ReferenceLoopHandling = ReferenceLoopHandling.Ignore

詳細說明：如何在 System.Text.Json 中保留引用

8.支援欄位(Field)

在序列化和反序列時支援欄位，欄位不能定義為 private。

public class Cat
{

    public string? Name { get; set; }

    public int _age;

    public Cat()
    {
        _age = 13;
    }
}

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: {"_age":13,"name":"xiaoshi"}

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
    IncludeFields = true // 或者 JsonIncludeAttribute
};


Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: {"name":"xiaoshi","_age":13}

System.Text.Json 預設不支援直接序列化和反序列化欄位，需要設定 IncludeFields = true或者 JsonIncludeAttribute 特性。

8.順序

自定義屬性在 Json 輸出中的順序：

public class Cat
{

    public string? Name { get; set; }

    [System.Text.Json.Serialization.JsonPropertyOrder(0)]
    [Newtonsoft.Json.JsonProperty(Order = 0)]
    public int Age { get; set; }
}

System.Text.Json 使用 JsonPropertyOrder，Newtonsoft.Json 使用 JsonProperty(Order)

9.位元組陣列

Newtonsoft.Json 不支援直接序列化為位元組陣列，System.Text.Json 支援直接序列化為 UTF-8 位元組陣列。

System.Text.Json：

var bytes = JsonSerializer.SerializeToUtf8Bytes(cat)

序列化為 UTF-8 位元組陣列比使用基於字串的方法大約快 5-10%。

10.重新命名

public class Cat
{

    public string? Name { get; set; }

    [System.Text.Json.Serialization.JsonPropertyName("catAge")]
    [Newtonsoft.Json.JsonProperty("catAge")]
    public int Age { get; set; }
}

重新命名 Json 屬性名稱，System.Text.Json 使用 JsonPropertyName，Newtonsoft.Json 使用 JsonProperty。

11.縮排

Newtonsoft.Json：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
    // this option
    Formatting = Newtonsoft.Json.Formatting.Indented,
};

Console.WriteLine(Newtonsoft.Json.JsonConvert.SerializeObject(cat,op));
// output: 
// {
//     "name": "xiaoshi",
//     "catAge": 0
// }

System.Text.Json

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
    // this option
    WriteIndented = true,
};


Console.WriteLine(System.Text.Json.JsonSerializer.Serialize(cat, options));
// output: 
// {
//     "name": "xiaoshi",
//     "catAge": 0
// }

三.反序列化

1.反序列化

定義：

public class Cat
{
    public string? Name { get; set; }
    public int Age { get; set; }
}

var json = """{"name":"xiaoshi","age":16} """;
Cat cat;

Newtonsoft.Json：

var op = new Newtonsoft.Json.JsonSerializerSettings()
{
    ContractResolver = new Newtonsoft.Json.Serialization.CamelCasePropertyNamesContractResolver(),
};

cat=Newtonsoft.Json.JsonConvert.DeserializeObject<Cat>(json, op);

Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
// output: CatName xiaoshi, Age 16

System.Text.Json：

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
};

cat=System.Text.Json.JsonSerializer.Deserialize<Cat>(json,options);

Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
// output: CatName xiaoshi, Age 16

變化 JsonConvert.DeserializeObject->JsonSerializer.Deserialize

2.允許註釋

在反序列化過程中，Newtonsoft.Json 在預設情況下會忽略 JSON 中的註釋。 System.Text.Json 預設是對註釋引發異常，因為 System.Text.Json 規範不包含它們。

var json = """
{
    "name": "xiaoshi", // cat name
    "age": 16
}
""";
Cat cat;

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
    // 不設定會引發異常
    ReadCommentHandling = System.Text.Json.JsonCommentHandling.Skip,
};

cat=System.Text.Json.JsonSerializer.Deserialize<Cat>(json,options);

Console.WriteLine($"CatName {cat.Name}, Age {cat.Age}");
// output: CatName xiaoshi, Age 16

設定 ReadCommentHandling=JsonCommentHandling.Skip即可忽略註釋。

詳細說明：如何使用 System.Text.Json 支援某種無效的 JSON

3.尾隨逗號

尾隨逗號即 Json 末尾為逗號：

無尾隨逗號：

{
    "name": "xiaoshi",
    "age": 16
}

有尾隨逗號：

{
    "name": "xiaoshi",
    "age": 16,
}

System.Text.Json 預設對尾隨逗號引發異常，可以透過 AllowTrailingCommas = true 來設定

var json = """
{
    "name": "xiaoshi",
    "age": 16,
}
""";
 Cat cat;
  
var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = System.Text.Json.JsonNamingPolicy.CamelCase,
    AllowTrailingCommas = true,
};

cat=System.Text.Json.JsonSerializer.Deserialize<Cat>(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 基於嚴格的標準出發，預設不支援，但是可配置。

var options = new System.Text.Json.JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    NumberHandling = JsonNumberHandling.AllowReadingFromString
};

// C# 11 原始字串
var json="""{"name":"xiaoshi","age":"13"}""";

Console.WriteLine(System.Text.Json.JsonSerializer.Deserialize<Cat>(json, options).Age);
// 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.Json	System.Text.Json
支援範圍廣泛的型別	⚠️ ⚠
將推斷型別反序列化為 `object` 屬性	⚠️ ⚠
將 JSON `null` 文字反序列化為不可為 null 的值型別	⚠️ ⚠
`DateTimeZoneHandling`、`DateFormatString` 設定	⚠️ ⚠
`JsonConvert.PopulateObject` 方法	⚠️ ⚠
`ObjectCreationHandling` 全域性設定	⚠️ ⚠
在不帶 setter 的情況下新增到集合	⚠️ ⚠
對屬性名稱採用蛇形命名法	⚠️ ⚠

以下功能 System.Text.Json 不支援：

Newtonsoft.Json	System.Text.Json
支援 `System.Runtime.Serialization` 特性	❌❌
`MissingMemberHandling` 全域性設定	❌❌
允許不帶引號的屬性名稱	❌❌
字串值前後允許單引號	❌❌
對字串屬性允許非字串 JSON 值	❌❌
`TypeNameHandling.All` 全域性設定	❌❌
支援 `JsonPath` 查詢	❌❌
可配置的限制	❌❌

五.結束

在 Ms Learn(Docs) 和 Google 之間頻繁切換寫完了這篇文章，希望對大家在從 Newtonsoft.Json 遷移到 System.Text.Json 有所幫助。就我個人而言我是打算使用 System.Text.Json 了。

參考資料

從Perforce遷移到Git
2014-05-21
Git
從 golang flag 遷移到 cmdr
2019-07-23
Golang
從 Nginx 遷移到 Envoy Proxy
2018-12-14
Nginx
[譯]從 SQLite 逐步遷移到 Room
2019-03-04
SQLiteOOM
從mpvue遷移到uni-app
2019-04-27
VueAPP
EF Core從TPH遷移到TPT
2023-04-04
[譯] 從 SQLite 逐步遷移到 Room
2018-03-26
SQLiteOOM
Linode從Xen遷移到KVM
2015-06-18
將表從mysql 遷移到oracle
2010-12-16
MySqlOracle
Azure VM從ASM遷移到ARM（二）
2017-06-23
ASM
Azure VM從ASM遷移到ARM（一）
2017-06-02
ASM
PayPal從Java遷移到Node.js
2013-11-29
JavaNode.js
從SpringMVC遷移到Springboot
2018-01-07
SpringMVCSpring Boot
使用DynamoShake從dynamodb遷移到mongodb
2019-09-05
MongoDB
從檔案系統遷移到ASM上
2018-02-05
ASM
oralce 從檔案系統遷移到ASM
2012-08-24
ASM
如果需要從Oracle遷移到MS SQLServer (2)
2009-12-19
OracleSQLServer
如果需要從Oracle遷移到MS SQLServer (1)
2009-12-19
OracleSQLServer
遷移到ASM
2010-03-07
ASM
從 CRUD 遷移到事件溯源的祕訣 - eventstore
2021-06-06
事件
Gradle指南之從Groovy遷移到Kotlin
2018-08-30
GradleKotlin
從RabbitMQ平滑遷移到RocketMQ技術實戰
2022-08-01
MQ
記錄從vuecli打包庫遷移到rollup打包
2022-06-08
Vue
從Firebase+Redis遷移到PlanetScale+MySQL
2021-11-16
RedisMySql
我為什麼從Redux遷移到了Mobx
2017-11-29
Redux
[譯] 將現有的 API 從 REST 遷移到 GraphQL
2017-08-12
APIREST
閃購網站Gilt從Rails遷移到Scala
2014-05-18
網站AI
將應用程式從Sql Server遷移到Oracle
2009-02-06
SQLServerOracle
從 PDF 表單遷移到 IBM Lotus Forms
2009-03-30
IBMORM
從關聯式資料庫遷移到CouchDB
2010-08-05
資料庫
為什麼我會從MongoDB遷移到PostgreSQL
2012-09-20
MongoDBSQL
Android技術棧(一)從Activity遷移到Fragment
2019-03-20
AndroidFragment
Spring Boot 從1.5遷移到2.0.5 - DZone Java
2019-01-16
Spring BootJava
從過時的 Windows 機器遷移到 Linux
2018-10-08
WindowsLinux
從eclipse遷移到idea(1 安裝篇)
2018-12-08
EclipseIdea
從單體遷移到微服務的十二種方法
2022-07-15
微服務
為何我們前端從Vue 2遷移到Svelte？
2022-12-02
前端Vue
平安科技從 Oracle 遷移到 UbiSQL 的實踐
2022-02-15
OracleSQL

從 Newtonsoft.Json 遷移到 System.Text.Json

一.寫在前面

二.序列化

1.序列化

2.忽略屬性

2.1 通用

2.2 忽略所有隻讀屬性

2.3 忽略所有 null 屬性

2.4 忽略所有預設值屬性

3.大小寫

4.字串轉義

5.自定義轉換器

6.迴圈引用

8.支援欄位(Field)

8.順序

9.位元組陣列

10.重新命名

11.縮排

三.反序列化

1.反序列化

2.允許註釋

3.尾隨逗號

4.帶引號數字

5.Json DOM

6.JsonConstructor

四.無法滿足的場景

五.結束

參考資料

相關文章