從 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

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 了。

從 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

四.無法滿足的場景

五.結束

參考資料