使用原生 System.Text.Json 命名空間處理 JSON

June 26th, 2019

一直以來，當要處理 JSON 的時候 Json.NET 是最佳的幫手，有非常順手的 API 和功能，讓開發者輕鬆處理 JSON 的大小事，甚至在 .NET 的各種函示庫、框架中都有用到，但當許多專案相依於此函示庫時，只要版本一更新，很容易造成許多專案要更著變動，造成相依的函示庫版本很難掌握，因此 .NET Team 發展了 System.Text.Json 來在 .NET 專案中取代 Json.NET 的依賴。

如果你是使用 .NET Core 3 以上版本，System.Text.Json 此函示庫已經包含在裡面了。當然你也可以自行透過 NuGet 來安裝 Preview 版本的 System.Text.Json 擴充套件來使用。

2019/07/23 推出了 Preview 7，這版有 Breaking Change，已修正此文章。

Json.NET 最常被使用的功能莫過於 JsonConvert.SerializeObject() 將物件序列化，以及 JsonConvert.DeserializeObject() 將 JSON 文字反序列化成物件，這兩個功能，我們就先來看看這兩個功能對應到 System.Text.Json 該如何使用。

System.Text.Json 底下有另一個專門在處理序列化的命名空間 System.Text.Json.Serialization，可以參考官方文件查看他所提供的 API 方法。

將物件序列化

假設我們有個 Student 類別如下：

class Student {
    public string Name { get; set; }
    public int Age { get; set; }
}

可以透過 JsonSerializer.Serialize() 這個靜態方法將物件序列化成 JSON 文字，用法如下：

var student = new Student {
    Name = "Poy Chang",
    Age = 20
};
var json = JsonSerializer.Serialize<Student>(student);

序列化的結果就會是像這樣：

{"Name":"Poy Chang","Age":20}

我們成功將物件序列化了，只是輸出的樣式稍微有一點不好看，如果能讓輸出結果排版一下，開發者在閱讀的時候，會比較好讀，這時可以加上 JsonSerializerOptions 設定，對輸出的結果做一些調整，透過設定 WriteIndented 屬性，可以將 JSON 文字加上縮排，作法如下：

var options = new JsonSerializerOptions
{
    WriteIndented = true
};
var json = JsonSerializer.Serialize<Student>(student, options);

如此一來輸出的 JSON 就會被格式化，讓我們能輕鬆閱讀。

{
  "Name": "Poy Chang",
  "Age": 20
}

Unicode 編碼

如果 C# 物件的屬性值本身就是 JSON 的時候，使用 JsonSerializer.Serialize() 時你會看到輸出的結果會有 Unicode 編碼，例如 " 會編碼成 \u0022，這是因為 System.Text.Json 預設會使用 Unicode 來進行比較安全的序列化作法，因此將字串內的特殊符號編碼成 Unicode，但這樣可能會有兩個問題，第一個是這容易造成 JSON 字串變大，畢盡一個 " 字符，會變六個字符 \u0022，第二個這編碼後結果比較不容易閱讀，若要解決這問題，可以參考以下做法：

var options = new JsonSerializerOptions
{
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
};
var json = JsonSerializer.Serialize<Student>(student, options);

另外一提，Newtonsoft.Json 預設也是這種非 Unicode 編碼的模式。

JsonSerializerOptions 還有其他屬性可以做調整，詳請查看官方文件。

將文字反序列化成物件

反過來，要將 JSON 文字轉換成物件也是經常遇到的情境，可以透過 JsonSerializer.Deserialize() 這個靜態方法將物件序列化成 JSON 文字，用法如下：

var json = "{\"Name\":\"Poy Chang\",\"Age\":20}";
var student = JsonSerializer.Deserialize<Student>(json);

使用起來是不是也非常簡單、順手，也幾乎和原本的 JSON.NET 一樣，看樣子可以很輕鬆的將命名空間直接從 Newtonsoft.Json 移轉到 System.Text.Json。

JSON 屬性裝飾器

如果手動調整序列化後的屬性名稱，而不想更動 C# 原本的屬性名稱，System.Text.Json.Serialization 有提供屬性裝飾器來讓開發者自行決定序列化後的結果，使用方式只要在屬性上面掛上裝飾器並設定要輸出的名稱即可，方法如下：

class Student {
    [JsonPropertyName("studentName")]
    public string Name { get; set; }
    [JsonPropertyName("studentAge")]
    public int Age { get; set; }
}

如此一來，透過 JsonSerializer.Serialize() 序列化的結過就是變成：

{
  "studentName": "Poy Chang",
  "studentAge": 20
}

如果你要轉換的屬性型別是 Enum 了話，可以在使用該 Enum 的屬性上掛上 [JsonConverter(typeof(JsonStringEnumConverter))] 屬性裝飾器，用法如下：

public enum Type
{
    GoodStudent,
    BadStudent
}

class Student {
    [JsonPropertyName("studentName")]
    public string Name { get; set; }
    [JsonConverter(typeof(JsonStringEnumConverter))]
    [JsonPropertyName("studentType")]
    public Type Type { get; set; }
}

如此一來，透過 JsonSerializer.Serialize() 序列化的結過就是變成：

{
    "studentName": "Poy Chang",
    "studentType": "GoodStudent"
}

後記

System.Text.Json 在處理 JSON 的速度以及記憶體的使用方面，都比 Json.NET 來的優秀，再加上 Json.NET 的作者 James Newton-King 也加入 Microsoft，未來這個套件勢必後勢看漲。同時 James 也表示，若是處理基本 JSON 轉換及查詢，使用 System.Text.Json 能獲得效能上的提升，但如果有特殊 JSON 處理的需求，Json.NET 仍然會持續開發、修正問題，依舊是一個不錯的解決方案。

參考資料：

Poy Chang

Trial and Error

Recent Posts