如何寫入 .NET 物件成為 JSON (序列化)
本文說明如何使用 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[][])。來自下列命名空間的集合和字典：
- System.Collections
- System.Collections.Generic
- System.Collections.Immutable
- System.Collections.Concurrent
- System.Collections.Specialized
- System.Collections.ObjectModel
如需詳細資訊，請參閱 System.Text.Json中支援的集合型別。
您可以實作自訂轉換器來處理其他型別，或提供內建轉換器不支援的功能。
以下範例顯示包含集合屬性和使用者定義型別的類別如何序列化：
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)
也可以使用採用 Utf8JsonWriter 的 Serialize 多載。
序列化為格式化 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 的程式碼。
如果您使用的是 Visual Studio 2022 版本 17.8 或更新版本，您可以嘗試在 Visual Studio 中使用由 AI 驅動的 GitHub Copilot 以產生使用 System.Text.Json 來序列化為 JSON 的程式碼。 在 Copilot 聊天視窗中將您的問題當成提示提交，如以下範例。 您也可以在編輯器視窗本身使用內嵌聊天來提交提示。
注意
GitHub Copilot 是由 AI 驅動的，因此可能會有意外和錯誤的情況發生。 任何生成的代碼或建議都務必要驗證。 有關 GitHub Copilot 的一般使用、產品影響、人為監督和隱私權的更多資訊，請參閱 [GitHub Copilot 常見問題解答]。
下列文字顯示 Copilot Chat 的範例提示：
產生程式碼，以使用
System.Text.Json將物件序列化為 JSON 字串。 物件包含下列欄位：FirstName (string)、Lastname (string)、Age (int)。 提供範例輸出。
您可以自訂提示，以使用符合您需求的物件欄位。
您可以使用聊天功能，例如 slash 命令、參考檔案、方法或類別，和執行緒，來設定意圖並取得範圍內容更好的解答。 針對在 IDE 中開啟之專案中的現有類別，您可以使用 /generate code to serialize #Classname in #Filename to JSON 提示 GitHub Copilot。
下列輸出顯示 Copilot Chat 回應的範例：
Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string in C#:
using System;
using System.Text.Json;
public class Person
{
public string FirstName { get; set; }
public string LastName { get; set; }
public int Age { get; set; }
}
public class Program
{
public static void Main()
{
var person = new Person
{
FirstName = "John",
LastName = "Doe",
Age = 30
};
string jsonString = JsonSerializer.Serialize(person);
Console.WriteLine(jsonString);
}
}
**Example Output**
{"FirstName":"John","LastName":"Doe","Age":30}
This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed to the console.
當 Copilot 傳回程式碼區塊時，回應會包含複製程式碼、將程式碼插入新檔案或預覽程式碼輸出的選項。
注意
您的結果可能會與範例回應中顯示的內容不同。 AI 模型不具決定性，這代表在詢問相同問題時，它們可能會傳回不同的回答。 這可能是由於隨著時間而進行的額外學習和調整、語言變化、上下文變化 (例如您的聊天記錄) 等因素造成的。
如需詳細資訊，請參閱
- GitHub Copilot 信任中心
- Visual Studio 中的 GitHub Copilot
- VS Code 中的 GitHub Copilot
