在 .NET 中將 JSON 序列化和還原序列化 (封送和解除封送) - 概觀

發行項
03/14/2024

System.Text.Json 命名空間提供序列化為 JavaScript 物件標記法 (JSON) 以及從 JSON 還原序列化的功能。序列化是將物件狀態轉換成可儲存或傳輸表單屬性值的程序。序列化表單不包含物件相關聯方法的任何資訊。還原序列化會從序列化形式重新建構物件。

比起廣泛的功能集，System.Text.Json 程式庫設計更強調的是高效能以及低記憶體配置。內建的 UTF-8 支援可在讀取和寫入編碼為 UTF-8 的 JSON 文字時將程序最佳化，而 UTF-8 是網路資料及磁碟檔案最常用的編碼方式。

程式庫也提供可使用記憶體內部文件物件模型 (DOM) 的類別。這項功能可讓您隨機存取 JSON 檔案或字串中的項目。

對於 Visual Basic，您可以使用的程式庫部分有一些限制。如需詳細資訊，請參閱 Visual Basic 支援。

如何取得程式庫

若為 .NET Core 3.0 和更新版本，程式庫會內建為共用架構的一部分。若為 .NET 6 和更新版本，則來源產生功能會內建為共用架構的一部分。

若架構版本早於 .NET Core 3.0，請安裝 System.Text.Json NuGet 套件。該套件支援下列版本：

.NET Standard 2.0 和更新版本
.NET Framework 4.6.2 和更新版本
.NET Core 2.1 和更新版本
.NET 5 和更新版本

命名空間和 API

System.Text.Json 命名空間包含所有進入點和主要型別。
System.Text.Json.Serialization 命名空間包含將進階案例的屬性和 API，以及特有的自訂序列化和還原序列化。

本文所示的程式碼範例需要這其中一個或兩個命名空間的 using 指示詞。

重要

System.Text.Json 不支援先前可能已使用的下列序列化 API：

System.Runtime.Serialization 命名空間的屬性。
System.SerializableAttribute 屬性和 ISerializable 介面。這些型別僅用於二進位和 XML 序列化。

HttpClient 和 HttpContent 擴充方法

從網路將 JSON 承載序列化和還原序列化是常見的作業。 HttpClient 和 HttpContent 上的擴充方法，可讓您在單行程式碼中執行這些作業。這些擴充方法會使用適用於 JsonSerializerOptions 的 Web 預設值。

下列範例示範如何使用 HttpClientJsonExtensions.GetFromJsonAsync 和 HttpClientJsonExtensions.PostAsJsonAsync：

using System.Net.Http.Json;

namespace HttpClientExtensionMethods
{
    public class User
    {
        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Username { get; set; }
        public string? Email { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            using HttpClient client = new()
            {
                BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
            };

            // Get the user information.
            User? user = await client.GetFromJsonAsync<User>("users/1");
            Console.WriteLine($"Id: {user?.Id}");
            Console.WriteLine($"Name: {user?.Name}");
            Console.WriteLine($"Username: {user?.Username}");
            Console.WriteLine($"Email: {user?.Email}");

            // Post a new user.
            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
            Console.WriteLine(
                $"{(response.IsSuccessStatusCode ? "Success" : "Error")} - {response.StatusCode}");
        }
    }
}

// Produces output like the following example but with different names:
//
//Id: 1
//Name: Tyler King
//Username: Tyler
//Email: Tyler @contoso.com
//Success - Created

Imports System.Net.Http
Imports System.Net.Http.Json

Namespace HttpClientExtensionMethods

    Public Class User
        Public Property Id As Integer
        Public Property Name As String
        Public Property Username As String
        Public Property Email As String
    End Class

    Public Class Program

        Public Shared Async Function Main() As Task
            Using client As New HttpClient With {
                .BaseAddress = New Uri("https://jsonplaceholder.typicode.com")
                }

                ' Get the user information.
                Dim user1 As User = Await client.GetFromJsonAsync(Of User)("users/1")
                Console.WriteLine($"Id: {user1.Id}")
                Console.WriteLine($"Name: {user1.Name}")
                Console.WriteLine($"Username: {user1.Username}")
                Console.WriteLine($"Email: {user1.Email}")

                ' Post a new user.
                Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("users", user1)
                Console.WriteLine(
                $"{(If(response.IsSuccessStatusCode, "Success", "Error"))} - {response.StatusCode}")
            End Using
        End Function

    End Class

End Namespace

' Produces output like the following example but with different names:
'
'Id: 1
'Name: Tyler King
'Username: Tyler
'Email: Tyler @contoso.com
'Success - Created

HttpContent 上也有 System.Text.Json 的擴充方法。

反映與來源產生

根據預設，System.Text.Json 會使用反映來收集存取物件屬性所需的中繼資料，以在執行階段進行序列化和還原序列化。作為替代方式，System.Text.Json 也可以使用 C# 來源產生功能來改善效能、減少私人記憶體用量，以及輔助組件調整，以降低應用程式大小。

如需詳細資訊，請參閱反映與來源產生。

安全性資訊

如需了解設計 JsonSerializer 時考量的安全性威脅，以及減輕這類威脅的方式，請參閱 System.Text.Json 威脅模型。

執行緒安全

System.Text.Json 序列化程式的設計考慮了執行緒安全性。實際上，這表示一旦鎖定，JsonSerializerOptions 執行個體就可以安全地跨多個執行緒共用。 JsonDocument 在 .NET 8 和更新版本中，提供 JSON 值不可變且安全執行緒的 DOM 表示法。

其他資源

如何使用程式庫

在 .NET 中將 JSON 序列化和還原序列化 (封送和解除封送) - 概觀

如何取得程式庫

命名空間和 API

HttpClient 和 HttpContent 擴充方法

反映與來源產生

安全性資訊

執行緒安全

其他資源

意見反應

其他資源