如何寫入 .NET 物件成為 JSON (序列化)

發行項
12/21/2024

本文說明如何使用 System.Text.Json 命名空間，針對 JavaScript 物件標記法 (JSON) 序列化。如果要從 Newtonsoft.Json 移植現有的程式碼，請參閱如何移轉至 System.Text.Json。

提示

您可以使用 AI 輔助來使用 GitHub Copilot 序列化為 JSON。

若要將 JSON 寫入字串或檔案，請呼叫 JsonSerializer.Serialize 方法。

序列化範例

下列範例會建立 JSON 作為字串：

using System.Text.Json;

namespace SerializeBasic
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim jsonString As String

根據預設，JSON 輸出會縮小（空格符、縮排和新行字元會移除）。

下列範例會使用同步程式碼來建立 JSON 檔案：

using System.Text.Json;

namespace SerializeToFile
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json"; 
            string jsonString = JsonSerializer.Serialize(weatherForecast);
            File.WriteAllText(fileName, jsonString);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(weatherForecast1)
File.WriteAllText(fileName, jsonString)

下列範例會使用非同步程式碼來建立 JSON 檔案：

using System.Text.Json;

namespace SerializeToFileAsync
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json";
            await using FileStream createStream = File.Create(fileName);
            await JsonSerializer.SerializeAsync(createStream, weatherForecast);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim createStream As FileStream = File.Create(fileName)
Await JsonSerializer.SerializeAsync(createStream, weatherForecast1)

上述範例會針對要序列化的型別使用型別推斷。 Serialize() 的多載會採用泛型型別參數：

using System.Text.Json;

namespace SerializeWithGenericParameter
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(Of WeatherForecastWithPOCOs)(weatherForecast)

您也可以使用 GitHub Copilot 為您產生序列化程式碼。如需指示，請參閱本文中的使用 GitHub Copilot 一節。

序列化行為

根據預設，所有公用屬性都會經過序列化。您可以指定要忽略的屬性。您也可以包含私人成員。
預設編碼器會逸出非 ASCII 字元、ASCII 範圍內的 HTML 敏感性字元，以及必須根據 RFC 8259 JSON 規格逸出的字元。
根據預設，JSON 會縮小。您可以美化顯示 JSON。
根據預設，JSON 名稱的大小寫符合 .NET 名稱。您可以自訂 JSON 名稱大小寫。
根據預設，會偵測迴圈參考，並擲回例外狀況。您可以保留參考和處理迴圈參考。
根據預設，會忽略欄位。您可以包含欄位。

您在 ASP.NET Core 應用程式中間接使用 System.Text.Json 時，某些預設行為會有所不同。如需詳細資訊，請參閱 JsonSerializerOptions 的 Web 預設值。

其他支援的型別包括：

對應至 JavaScript 基本型別的 .NET 基本型別，例如數值型別、字串和布林值。
使用者定義的簡單的 CLR 物件 (POCO)。
一維和不規則陣列 (T[][])。
來自下列命名空間的集合和字典：
如需詳細資訊，請參閱中支援的類型。

您可以實作自訂轉換器來處理其他型別，或提供內建轉換器不支援的功能。

以下範例顯示包含集合屬性和使用者定義型別的類別如何序列化：

using System.Text.Json;

namespace SerializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot",
                SummaryField = "Hot",
                DatesAvailable = new List<DateTimeOffset>() 
                    { DateTime.Parse("2019-08-01"), DateTime.Parse("2019-08-02") },
                TemperatureRanges = new Dictionary<string, HighLowTemps>
                    {
                        ["Cold"] = new HighLowTemps { High = 20, Low = -10 },
                        ["Hot"] = new HighLowTemps { High = 60 , Low = 20 }
                    },
                SummaryWords = new[] { "Cool", "Windy", "Humid" }
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot",
//  "DatesAvailable": [
//    "2019-08-01T00:00:00-07:00",
//    "2019-08-02T00:00:00-07:00"
//  ],
//  "TemperatureRanges": {
//    "Cold": {
//      "High": 20,
//      "Low": -10
//    },
//    "Hot": {
//    "High": 60,
//      "Low": 20
//    }
//  },
//  "SummaryWords": [
//    "Cool",
//    "Windy",
//    "Humid"
//  ]
//}

Public Class WeatherForecastWithPOCOs
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String
    Public SummaryField As String
    Public Property DatesAvailable As IList(Of DateTimeOffset)
    Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
    Public Property SummaryWords As String()
End Class

Public Class HighLowTemps
    Public Property High As Integer
    Public Property Low As Integer
End Class

' serialization output formatted (pretty-printed with whitespace and indentation):
' {
'   "Date": "2019-08-01T00:00:00-07:00",
'   "TemperatureCelsius": 25,
'   "Summary": "Hot",
'   "DatesAvailable": [
'     "2019-08-01T00:00:00-07:00",
'     "2019-08-02T00:00:00-07:00"
'   ],
'   "TemperatureRanges": {
'     "Cold": {
'       "High": 20,
'       "Low": -10
'     },
'     "Hot": {
'       "High": 60,
'       "Low": 20
'     }
'   },
'   "SummaryWords": [
'     "Cool",
'     "Windy",
'     "Humid"
'   ]
' }

將其序列化至 UTF-8

序列化至 UTF-8 位元組陣列的速度比使用字串型方法快 5-10%。這是因為位元組 (UTF-8) 不需要轉換成字串 (UTF-16)。

如果要將其序列化至 UTF-8 位元組陣列，請呼叫 JsonSerializer.SerializeToUtf8Bytes 方法：

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

也可以使用採用 Serialize 的 Utf8JsonWriter 多載。

序列化為格式化 JSON

如果要美化顯示 JSON 輸出，請將 JsonSerializerOptions.WriteIndented 設定為 true：

using System.Text.Json;

namespace SerializeWriteIndented
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot"
//}

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

從 .NET 9 開始，您也可以使用 IndentCharacter 和 IndentSize自訂縮排字元和大小。

提示

如果您搭配相同選項重複使用 JsonSerializerOptions，請勿在每次使用它時建立新的 JsonSerializerOptions 執行個體。針對每個呼叫重複使用相同的執行個體。如需詳細資訊，請參閱重複使用 JsonSerializerOptions 執行個體 (機器翻譯)。

使用 GitHub Copilot 以序列化為 JSON

您可以在 IDE 中使用 GitHub Copilot 以產生使用 System.Text.Json 來序列化為 JSON 的程式碼。您可以自訂提示，以使用符合您需求的物件欄位。

下列文字顯示 Copilot Chat 的範例提示：

Generate code to use System.Text.Json to serialize an object to a JSON string.
The object contains the following fields: FirstName (string), Lastname (string), Age (int).
Provide example output.

GitHub Copilot 是由 AI 驅動的，因此可能會有意外和錯誤的情況發生。如需詳細資訊，請參閱 Copilot 常見問題。

深入瞭解在 Visual Studio 中的 GitHub Copilot 和在 VS Code 中的 GitHub Copilot 。

共用方式為