From: 011netservice@gmail.com
Date: 2024-12-19
Subject: CodeHelper System.Text.Json

https://svc.011.idv.tw/CodeHelper/cs/KeyWord/Json.txt
歡迎來信交流, 訂購軟體需求.

目錄:
- Json Samples:
- 序列化
- 還原序列化
- 讀取/寫入 JSON(不使用 JsonSerializer)


ref:
using System.Text.Json;
https://learn.microsoft.com/zh-tw/dotnet/standard/serialization/system-text-json/how-to




#### Json Samples:

**** Different styles nested JSON objects
https://stackoverflow.com/questions/2098276/nested-json-objects-do-i-have-to-use-arrays-for-everything

Nest_Sample1:
{"data":[{"stuff":[
    {"onetype":[
        {"id":1,"name":"John Doe"},
        {"id":2,"name":"Don Joeh"}
    ]},
    {"othertype":[
        {"id":2,"company":"ACME"}
    ]}]
},{"otherstuff":[
    {"thing":
        [[1,42],[2,2]]
    }]
}]}
result.data[0].stuff[0].onetype[0]
result.data[1].otherstuff[0].thing[0]

Nest_Sample2: 
Different style to store Nest_Sample1 above.
JSON values can be arrays, objects, or primitives (numbers or strings):
{ 
    "stuff": {
        "onetype": [
            {"id":1,"name":"John Doe"},
            {"id":2,"name":"Don Joeh"}
        ],
        "othertype": {"id":2,"company":"ACME"}
    }, 
    "otherstuff": {
        "thing": [[1,42],[2,2]]
     }
}
obj.stuff.onetype[0].id
obj.stuff.othertype.id
obj.otherstuff.thing[0][1]  
//thing is a nested array or a 2-by-2 matrix.



#### 序列化
**** 序列化
如何序列化
*** 序列化範例
下列範例會建立 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"}

根據預設，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"}

*** 下列範例會使用非同步程式碼來建立 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"}

*** 上述範例會針對要序列化的型別使用型別推斷。 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"}

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

根據預設，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"
//  ]
//}

*** 將其序列化至 UTF-8
序列化至 UTF-8 位元組陣列的速度比使用字串型方法快 5-10%。 這是因為位元組 (UTF-8) 不需要轉換成字串 (UTF-16)。
如果要將其序列化至 UTF-8 位元組陣列，請呼叫 JsonSerializer.SerializeToUtf8Bytes 方法：
byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);


*** 序列化為格式化 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"
//}

**** 自訂屬性名稱與值
*** 如何使用 System.Text.Json 自訂屬性名稱與值
根據預設，JSON 輸出中的屬性名稱和字典索引鍵會保持不變 (包括大小寫)。 列舉值會以數字表示。 屬性會依其定義的順序進行序列化。 不過，您可以透過下列方式自訂這些行為：

指定特定的序列化屬性名稱。
針對屬性名稱和字典索引鍵，使用內建命名原則，例如駝峰式大小寫、蛇式大小寫或肉串式大小寫。
針對屬性名稱和字典索引鍵使用自訂命名原則。
使用或不使用命名原則，將列舉值序列化為字串。
設定序列化屬性的順序。

*** 自訂個別屬性名稱
如果要設定個別屬性 (Property) 的名稱，請使用 [JsonPropertyName] 屬性 (Attribute)。

以下是要序列化的範例類型與產生的 JSON：
public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "Wind": 35
}
此屬性 (Attribute) 所設定的屬性 (Property) 名稱：
1. 序列化和還原序列化雙向適用。
2. 優先順序高於屬性命名原則。
3. 不會影響參數化建構函式的參數名稱比對。



*** 使用內建命名原則
下表顯示內建命名原則，及其如何影響屬性名稱。
命名原則        描述                                     原名        結果
--------------- ---------------------------------------- ----------- ------------
CamelCase	    第一個字小寫字元開頭, 其餘大寫字元開頭。 TempCelsius tempCelsius
KebabCaseLower* 全部小寫, 單字會以連字號分隔。           TempCelsius temp-celsius
KebabCaseUpper* 全部大寫, 單字會以連字號分隔。           TempCelsius TEMP-CELSIUS
SnakeCaseLower* 全部小寫, 單字會以底線分隔。             TempCelsius temp_celsius
SnakeCaseUpper* 全部大寫, 單字會以底線分隔。             TempCelsius TEMP_CELSIUS

* 在 .NET 8 版和更新版本中可供使用。

下列範例示範如何藉由將 JsonSerializerOptions.PropertyNamingPolicy 設定為 JsonNamingPolicy.CamelCase，針對所有 JSON 屬性名稱使用駝峰式大小寫：
var serializeOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

以下是要序列化的範例類別與 JSON 輸出：
public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "date": "2019-08-01T00:00:00-07:00",
  "temperatureCelsius": 25,
  "summary": "Hot",
  "Wind": 35
}
命名原則：
1. 適用於序列化與還原序列化。
2. 由 [JsonPropertyName] 屬性覆寫。 這就是範例中的 JSON 屬性名稱 Wind 不是駝峰式大小寫的原因。

*** 使用自訂 JSON 屬性命名原則
如果要使用自訂 JSON 屬性命名原則，可建立衍生自 JsonNamingPolicy 的類別，並覆寫 ConvertName 方法，如下列範例所示：
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class UpperCaseNamingPolicy : JsonNamingPolicy
    {
        public override string ConvertName(string name) =>
            name.ToUpper();
    }
}
然後，將 JsonSerializerOptions.PropertyNamingPolicy 屬性設定為命名原則類別的執行個體：
var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = new UpperCaseNamingPolicy(),
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

以下是要序列化的範例類別與 JSON 輸出：
public class WeatherForecastWithPropertyName
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
    [JsonPropertyName("Wind")]
    public int WindSpeed { get; set; }
}
{
  "DATE": "2019-08-01T00:00:00-07:00",
  "TEMPERATURECELSIUS": 25,
  "SUMMARY": "Hot",
  "Wind": 35
}
JSON 屬性命名原則：

1. 適用於序列化與還原序列化。
2. 由 [JsonPropertyName] 屬性覆寫。 這就是範例中 JSON 屬性名稱 Wind 不是大寫的原因。

*** 使用字典索引鍵的命名原則
如果要序列化物件的屬性是 Dictionary<string,TValue> 類型，則可以使用命名原則來轉換 string 索引鍵，例如駝峰式大小寫。 若要這樣做，請將 JsonSerializerOptions.DictionaryKeyPolicy 設定為您想要的命名原則。 下列範例使用 CamelCase 命名原則：
var options = new JsonSerializerOptions
{
    DictionaryKeyPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

使用具有機碼值組 "ColdMinTemp", 20 和 "HotMinTemp", 40 且名為 TemperatureRanges 的字典來將物件序列化會產生 JSON 輸出，如下列範例所示：
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "Hot",
  "TemperatureRanges": {
    "coldMinTemp": 20,
    "hotMinTemp": 40
  }
}
字典索引鍵的命名原則僅適用於序列化。 如果您還原序列化字典，即使將 JsonSerializerOptions.DictionaryKeyPolicy 設定為非預設命名原則，索引鍵也會符合 JSON 檔案。


*** 以字串表示列舉
根據預設，會將列舉序列化為數字。 若要將列舉名稱序列化為字串，請使用 JsonStringEnumConverter 或 JsonStringEnumConverter<TEnum> 轉換器。 只有原生 AOT 執行階段才支援 JsonStringEnumConverter<TEnum>。

例如，假設您需要將下列具有列舉的類別序列化：
public class WeatherForecastWithEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Summary? Summary { get; set; }
}

public enum Summary
{
    Cold, Cool, Warm, Hot
}

如果摘要是 Hot，則根據預設，序列化的 JSON 會有數值 3：
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": 3
}

下列範例程式碼會將列舉名稱 (而非數值) 序列化，並將名稱轉換為駝峰式大小寫：
options = new JsonSerializerOptions
{
    WriteIndented = true,
    Converters =
    {
        new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)
    }
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

產生的 JSON 類似下列範例：
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Summary": "hot"
}

內建的 JsonStringEnumConverter 也可以將字串值還原序列化。 它可以使用或不使用指定的命名原則來運作。 下列範例示範如何使用 CamelCase 來還原序列化：
options = new JsonSerializerOptions
{
    Converters =
    {
        new JsonStringEnumConverter(JsonNamingPolicy.CamelCase)
    }
};
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithEnum>(jsonString, options)!;

您也可以指定要使用的轉換器，方法是將列舉標註為 JsonConverterAttribute。 下列範例示範如何使用 JsonConverterAttribute 屬性來指定 JsonStringEnumConverter<TEnum> (在 .NET 8 和更新版本中提供)。 例如，假設您需要將下列具有列舉的類別序列化：
public class WeatherForecastWithPrecipEnum
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public Precipitation? Precipitation { get; set; }
}

[JsonConverter(typeof(JsonStringEnumConverter<Precipitation>))]
public enum Precipitation
{
    Drizzle, Rain, Sleet, Hail, Snow
}

下列範例程式碼會序列化列舉名稱，而不是數值：


public class WeatherForecastWithIgnoreAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    [JsonIgnore]
    public string? Summary { get; set; }
}
var options = new JsonSerializerOptions
{
    WriteIndented = true,
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

產生的 JSON 類似下列範例：
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
  "Precipitation": "Sleet"
}
若要搭配來源產生使用轉換器，請參閱將列舉欄位序列化為字串。


*** 設定序列化屬性的順序
根據預設，屬性會依其類別中定義的順序進行序列化。 [JsonPropertyOrder] 屬性 (Attribute) 可讓您在序列化期間，指定 JSON 輸出中的屬性 (Property) 順序。 Order 屬性的預設值為零。 將 Order 設定為正數，以將屬性放置於具有預設值的屬性之後。 負數的 Order 會將屬性放置於具有預設值的屬性之前。 屬性會依從最低 Order 值到最高值的順序寫入。 以下是範例：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace PropertyOrder
{
    public class WeatherForecast
    {
        [JsonPropertyOrder(-5)]
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        [JsonPropertyOrder(-2)]
        public int TemperatureF { get; set; }
        [JsonPropertyOrder(5)]
        public string? Summary { get; set; }
        [JsonPropertyOrder(2)]
        public int WindSpeed { get; set; }
    }

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

            var options = new JsonSerializerOptions { WriteIndented = true };
            string jsonString = JsonSerializer.Serialize(weatherForecast, options);
            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00",
//  "TemperatureF": 25,
//  "TemperatureC": 25,
//  "WindSpeed": 10,
//  "Summary": "Hot"
//}

**** 忽略屬性
將 C# 物件序列化為 JavaScript 物件標記法 (JSON) 時，所有公用屬性預設都會序列化。 如果不想讓其中某些屬性出現在產生的 JSON 中，有幾個選項可供選擇。 在本文中，您將了解如何根據各種準則忽略屬性：
1. 個別屬性
2. 所有唯讀屬性
3. 所有 Null 值屬性
4. 所有預設值屬性

** 忽略個別屬性
若要忽略個別屬性，請使用 [JsonIgnore] 屬性。

下例示範要序列化的類型。 它也會顯示 JSON 輸出：
public class WeatherForecastWithIgnoreAttribute
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    [JsonIgnore]
    public string? Summary { get; set; }
}
{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25,
}

您可以設定 [JsonIgnore] 屬性 (Attribute) 的 Condition 屬性 (Property) 來指定條件式排除。 JsonIgnoreCondition 列舉提供下列選項：
1. Always - 一律忽略屬性。 如果未指定任何 Condition，則會假設為此選項。
2. Never - 無論DefaultIgnoreCondition、IgnoreReadOnlyProperties 和 IgnoreReadOnlyFields 全域設定為何，一律會序列化與還原序列化該屬性。
3. WhenWritingDefault - 若為參考型別 null、可為 Null 的實值型別 null 或實值型別 default，則會在序列化時忽略該屬性。
4. WhenWritingNull - 若為參考型別 null 或可為 Null 的實值型別 null，則會在序列化時忽略該屬性。
下例示範如何使用 [JsonIgnore] 屬性 (Attribute) 的 Condition 屬性 (Property)：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace JsonIgnoreAttributeExample
{
    public class Forecast
    {
        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingDefault)]
        public DateTime Date { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.Never)]
        public int TemperatureC { get; set; }

        [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = default,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
            };

            string forecastJson =
                JsonSerializer.Serialize<Forecast>(forecast,options);

            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{"TemperatureC":0}



** 忽略所有唯讀屬性
如果屬性包含公用 getter，卻不包含公用 setter，則屬性即為唯讀。 若要在序列化時忽略所有唯讀屬性，請將 JsonSerializerOptions.IgnoreReadOnlyProperties 設定為 true，如下列範例所示：
var options = new JsonSerializerOptions
{
    IgnoreReadOnlyProperties = true,
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, options);

此選項僅適用於屬性。 若要在序列化欄位時忽略唯讀欄位，請使用 JsonSerializerOptions.IgnoreReadOnlyFields 全域設定。


** 忽略所有 Null 值屬性
若要忽略所有 Null 值屬性，請將 DefaultIgnoreCondition 屬性設定為 WhenWritingNull，如下列範例所示：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace IgnoreNullOnSerialize
{
    public class Forecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = DateTime.Now,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
            };

            string forecastJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);
            
            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{"Date":"2020-10-30T10:11:40.2359135-07:00","TemperatureC":0}


** 忽略所有預設值屬性
若要防止實值型別屬性中的預設值序列化，請將 DefaultIgnoreCondition 屬性設定為 WhenWritingDefault，如下列範例所示：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace IgnoreValueDefaultOnSerialize
{
    public class Forecast
    {
        public DateTime Date { get; set; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = DateTime.Now,
                Summary = null,
                TemperatureC = default
            };

            JsonSerializerOptions options = new()
            {
                DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
            };

            string forecastJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine(forecastJson);
        }
    }
}

// Produces output like the following example:
//
//{ "Date":"2020-10-21T15:40:06.8920138-07:00"}
此 WhenWritingDefault 設定也會防止 Null 值參考型別和可為 Null 實值型別屬性序列化。


**** 包含欄位
根據預設，欄位不會序列化。
使用 JsonSerializerOptions.IncludeFields 全域設定或 [JsonInclude] 屬性，在序列化或還原序列化時包含欄位，如下列範例所示：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace Fields
{
    public class Forecast
    {
        public DateTime Date;
        public int TemperatureC;
        public string? Summary;
    }

    public class Forecast2
    {
        [JsonInclude]
        public DateTime Date;
        [JsonInclude]
        public int TemperatureC;
        [JsonInclude]
        public string? Summary;
    }

    public class Program
    {
        public static void Main()
        {
            string json = """
                {
                    "Date":"2020-09-06T11:31:01.923395",
                    "TemperatureC":-1,
                    "Summary":"Cold"
                }
                """;
            Console.WriteLine($"Input JSON: {json}");

            var options = new JsonSerializerOptions
            {
                IncludeFields = true,
            };
            Forecast forecast = JsonSerializer.Deserialize<Forecast>(json, options)!;

            Console.WriteLine($"forecast.Date: {forecast.Date}");
            Console.WriteLine($"forecast.TemperatureC: {forecast.TemperatureC}");
            Console.WriteLine($"forecast.Summary: {forecast.Summary}");

            string roundTrippedJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine($"Output JSON: {roundTrippedJson}");

            Forecast2 forecast2 = JsonSerializer.Deserialize<Forecast2>(json)!;

            Console.WriteLine($"forecast2.Date: {forecast2.Date}");
            Console.WriteLine($"forecast2.TemperatureC: {forecast2.TemperatureC}");
            Console.WriteLine($"forecast2.Summary: {forecast2.Summary}");

            roundTrippedJson = JsonSerializer.Serialize<Forecast2>(forecast2);
            
            Console.WriteLine($"Output JSON: {roundTrippedJson}");
        }
    }
}

// Produces output like the following example:
//
//Input JSON: { "Date":"2020-09-06T11:31:01.923395","TemperatureC":-1,"Summary":"Cold"}
//forecast.Date: 9/6/2020 11:31:01 AM
//forecast.TemperatureC: -1
//forecast.Summary: Cold
//Output JSON: { "Date":"2020-09-06T11:31:01.923395","TemperatureC":-1,"Summary":"Cold"}
//forecast2.Date: 9/6/2020 11:31:01 AM
//forecast2.TemperatureC: -1
//forecast2.Summary: Cold
//Output JSON: { "Date":"2020-09-06T11:31:01.923395","TemperatureC":-1,"Summary":"Cold"}

如果要忽略唯讀欄位，請使用 JsonSerializerOptions.IgnoreReadOnlyFields 全域設定。


#### 還原序列化
**** 還原序列化
如何還原序列化
https://learn.microsoft.com/zh-tw/dotnet/standard/serialization/system-text-json/deserialization
將 JSON 還原序列化的常見方式是擁有 (或建立) 具有屬性和欄位的 .NET 類別，這些代表一個或多個 JSON 屬性。
 然後，若要將字串或檔案還原序列化，請呼叫 JsonSerializer.Deserialize 方法。 
 針對泛型多載，泛型型別參數是 .NET 類別。 針對非泛型多載，您會傳遞類別型別做為方法參數。 
 您可以同步或非同步還原序列化。

根據預設，系統會忽略類別中未表示的任何 JSON 屬性。 
此外，如果型別上的任何屬性是必要的，但不存在於 JSON 承載中，還原序列化將會失敗。

*** 範例 
下列範例示範如何將 JSON 字串還原序列化：
using System.Text.Json;

namespace DeserializeExtra
{
    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()
        {
            string jsonString =
                """
                {
                  "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"
                  ]
                }
                """;
                
            WeatherForecast? weatherForecast = 
                JsonSerializer.Deserialize<WeatherForecast>(jsonString);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

若要使用同步程式碼從檔案還原序列化，請將檔案讀入字串，如下列範例所示：
using System.Text.Json;

namespace DeserializeFromFile
{
    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()
        {
            string fileName = "WeatherForecast.json";
            string jsonString = File.ReadAllText(fileName);
            WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString)!;

            Console.WriteLine($"Date: {weatherForecast.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot

若要使用非同步程式碼將檔案還原序列化，請呼叫 DeserializeAsync 方法：
using System.Text.Json;

namespace DeserializeFromFileAsync
{
    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()
        {
            string fileName = "WeatherForecast.json";
            using FileStream openStream = File.OpenRead(fileName);
            WeatherForecast? weatherForecast = 
                await JsonSerializer.DeserializeAsync<WeatherForecast>(openStream);

            Console.WriteLine($"Date: {weatherForecast?.Date}");
            Console.WriteLine($"TemperatureCelsius: {weatherForecast?.TemperatureCelsius}");
            Console.WriteLine($"Summary: {weatherForecast?.Summary}");
        }
    }
}
// output:
//Date: 8/1/2019 12:00:00 AM -07:00
//TemperatureCelsius: 25
//Summary: Hot



*** 還原序列化行為
還原序列化 JSON 時，下列行為適用：

根據預設，屬性名稱比對會區分大小寫。 您可以指定不區分大小寫。
序列化程式會忽略非公用建構函式。
支援還原序列化為不可變的物件或沒有公用 set 存取子的屬性，但預設不會啟用。 請參閱不可變的型別和記錄。
根據預設，支援列舉為數字。 您可以還原序列化字串列舉欄位。
根據預設，會忽略欄位。 您可以包含欄位。
根據預設，JSON 中的註解或後置逗號會擲回例外狀況。 您可以允許註解和後置逗號。
預設的最大深度為 64。


*** 不使用 .NET 類別還原序列化
如果您想要將 JSON 還原序列化，而且沒有要還原序列化的類別，則您會有手動建立所需類別以外的選項：

直接使用 Utf8JsonReader。

還原序列化為 JSON DOM (文件物件模型)，並從 DOM 擷取所需內容。

DOM 可讓您瀏覽至 JSON 承載的子區段，並將單一值、自訂型別或陣列還原序列化。 如需 JsonNode DOM 相關資訊，請參閱還原序列化 JSON 承載的子區段。 如需 DOM 的資訊，請參閱JsonDocument如何搜尋子項目的 JsonDocument 和 JsonElement。

使用 Visual Studio 2022 自動產生您需要的類別：

複製還原序列化所需的 JSON。
建立類別檔案並刪除範本程式碼。
選擇 [編輯] > [選擇性貼上] > [將 JSON 貼上為類別]。
結果為可用在將目標還原序列化的類別。

*** 從 UTF-8 將其還原序列化
如果要從 UTF-8 將其還原序列化，請呼叫採用 ReadOnlySpan<byte> 或 Utf8JsonReader 的 JsonSerializer.Deserialize 多載，
如下列範例所示。 
這些範例假設 JSON 位於名稱為 jsonUtf8Bytes 的位元組陣列中。
var readOnlySpan = new ReadOnlySpan<byte>(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(readOnlySpan)!;
	
var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
WeatherForecast deserializedWeatherForecast = 
    JsonSerializer.Deserialize<WeatherForecast>(ref utf8Reader)!;
	
	
**** 必要屬性:
從 .NET 7 開始，您可以標記特定屬性，表示它們必須存在於 JSON 承載中，還原序列化才能成功。 
如果這其中一或多個必要屬性不存在，JsonSerializer.Deserialize 方法就會擲回 JsonException。

有三種方式可將屬性或欄位標記為 JSON 還原序列化所需的項目：
1. 新增必要的修飾元，此為 C# 11 的新功能。
2. 使用 JsonRequiredAttribute 進行標註，此為 .NET 7 的新功能。
3. 修改合約模型的 JsonPropertyInfo.IsRequired 屬性，此為 .NET 7 的新功能。

從序列化程式的觀點來看，這兩個劃分都一樣，而且這兩者都會對應至相同的中繼資料片段，也就是 JsonPropertyInfo.IsRequired。 在大部分情況下，您只要使用內建的 C# 關鍵字即可。 不過，在下列情況下，您應該改用 JsonRequiredAttribute：
1. 如果您使用的是 C# 或舊版 C# 以外的程式設計語言。
2. 如果您只想將需求套用至 JSON 還原序列化。
3. 如果您在來源產生模式中使用 System.Text.Json 序列化。 在此情況下，如果您使用 required 修飾元，您的程式碼將不會編譯，因為來源產生會在編譯時間發生。


下列程式碼片段顯示使用 required 關鍵字修改的屬性範例。 此屬性必須存在於 JSON 承載中，還原序列化才能成功。
using System.Text.Json;

// The following line throws a JsonException at run time.
Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));

public class Person
{
    public required string Name { get; set; }
    public int Age { get; set; }
}

或者，您可以使用 JsonRequiredAttribute：
using System.Text.Json;

// The following line throws a JsonException at run time.
Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));

public class Person
{
    [JsonRequired]
    public string Name { get; set; }
    public int Age { get; set; }
}

您也可以使用 JsonPropertyInfo.IsRequired 屬性，透過合約模型來控制是否需要屬性：
var options = new JsonSerializerOptions
{
    TypeInfoResolver = new DefaultJsonTypeInfoResolver
    {
        Modifiers =
        {
            static typeInfo =>
            {
                if (typeInfo.Kind != JsonTypeInfoKind.Object)
                    return;

                foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
                {
                    // Strip IsRequired constraint from every property.
                    propertyInfo.IsRequired = false;
                }
            }
        }
    }
};

// Deserialization now succeeds even though the Name property isn't in the JSON payload.
JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);



**** 允許不正確 JSON
*** 允許註解和後置逗號:
JSON 中預設不允許註解和後置逗號。
若要在 JSON 中允許註解，請將 JsonSerializerOptions.ReadCommentHandling 屬性設定為 JsonCommentHandling.Skip。 
若要允許後置逗號，請將 JsonSerializerOptions.AllowTrailingCommas 屬性設定為 true。 
下列範例示範如何允許這兩者：
var options = new JsonSerializerOptions
{
    ReadCommentHandling = JsonCommentHandling.Skip,
    AllowTrailingCommas = true,
};
WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(
    jsonString,
    options
    )!;


{
  "Date": "2019-08-01T00:00:00-07:00",
  "TemperatureCelsius": 25, // Fahrenheit 77
  "Summary": "Hot", / * Zharko * / 因註解衝突, 改成空格在 * / 之間
  // Comments on
  / * separate lines * / 因註解衝突, 改成空格在 * / 之間
}

*** 允許或寫入引號中的數字
例如:
{
    "DegreesCelsius": "23"
}

若要將引號中的數字序列化，或接受整個輸入物件圖的引號中數字，
請設定 JsonSerializerOptions.NumberHandling，如下列範例所示：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace QuotedNumbers
{
    public class Forecast
    {
        public DateTime Date { get; init; }
        public int TemperatureC { get; set; }
        public string? Summary { get; set; }
    };

    public class Program
    {
        public static void Main()
        {
            Forecast forecast = new()
            {
                Date = DateTime.Now,
                TemperatureC = 40,
                Summary = "Hot"
            };

            JsonSerializerOptions options = new()
            {
                NumberHandling =
                    JsonNumberHandling.AllowReadingFromString |
                    JsonNumberHandling.WriteAsString,
                WriteIndented = true
            };

            string forecastJson =
                JsonSerializer.Serialize<Forecast>(forecast, options);

            Console.WriteLine($"Output JSON:\n{forecastJson}");

            Forecast forecastDeserialized =
                JsonSerializer.Deserialize<Forecast>(forecastJson, options)!;

            Console.WriteLine($"Date: {forecastDeserialized.Date}");
            Console.WriteLine($"TemperatureC: {forecastDeserialized.TemperatureC}");
            Console.WriteLine($"Summary: {forecastDeserialized.Summary}");
        }
    }
}

// Produces output like the following example:
//
//Output JSON:
//{
//  "Date": "2020-10-23T12:27:06.4017385-07:00",
//  "TemperatureC": "40",
//  "Summary": "Hot"
//}
//Date: 10/23/2020 12:27:06 PM
//TemperatureC: 40
//Summary: Hot




#### 讀取/寫入 JSON(而不使用 JsonSerializer)
https://learn.microsoft.com/zh-tw/dotnet/standard/serialization/system-text-json/use-dom

**** 使用 DOM 
如何在 System.Text.Json 中使用 JSON 文件物件模型
*** JSON DOM 選項

使用 DOM 是利用 JsonSerializer 還原序列化替代方法的情境：
1. 您沒有要還原序列化的類型。
2. 您收到的 JSON 沒有固定結構描述，必須加以檢查才能知道其所包含的內容時。


System.Text.Json 提供兩種方式來建置 JSON DOM：
1. JsonDocument 提供使用 Utf8JsonReader 建置唯讀 DOM 的功能。
 撰寫承載的 JSON 元素可以透過 JsonElement 類型存取。 
 JsonElement 類型提供陣列和物件列舉程式，以及將 JSON 文字轉換為一般.NET 類型的 API。
 JsonDocument 會公開 RootElement 屬性。 
 如需詳細資訊，請參閱本文件稍後的使用 JsonDocument。

2. JsonNode 和在 System.Text.Json.Nodes 命名空間中自其衍生的類別，提供建立可變 DOM 的功能。 
撰寫承載的 JSON 項目可以透過 JsonNode、JsonObject、JsonArray、JsonValue 和 JsonElement 類型存取。 
如需詳細資訊，請參閱本文稍後的使用 JsonNode。

在 JsonDocument 和 JsonNode 之間選擇時，請考慮下列因素：
1. JsonNode DOM 可以在建立之後變更。 JsonDocument DOM 是不可變的。
2. JsonDocument DOM 可讓您更快速地存取其資料。

*** 使用 JsonNode

下列範例示範如何使用 JsonNode 和 System.Text.Json.Nodes 命名空間中的其他類型：
1. 從 JSON 字串建立 DOM
2. 從 DOM 撰寫 JSON。
3. 從 DOM 取得值、物件或陣列。
using System.Text.Json;
using System.Text.Json.Nodes;

namespace JsonNodeFromStringExample;

public class Program
{
    public static void Main()
    {
        string jsonString = """
            {
              "Date": "2019-08-01T00:00:00",
              "Temperature": 25,
              "Summary": "Hot",
              "DatesAvailable": [
                "2019-08-01T00:00:00",
                "2019-08-02T00:00:00"
              ],
              "TemperatureRanges": {
                  "Cold": {
                      "High": 20,
                      "Low": -10
                  },
                  "Hot": {
                      "High": 60,
                      "Low": 20
                  }
              }
            }
            """;
        // Create a JsonNode DOM from a JSON string.
        JsonNode forecastNode = JsonNode.Parse(jsonString)!;

        // Write JSON from a JsonNode
        var options = new JsonSerializerOptions { WriteIndented = true };
        Console.WriteLine(forecastNode!.ToJsonString(options));
        // output:
        //{
        //  "Date": "2019-08-01T00:00:00",
        //  "Temperature": 25,
        //  "Summary": "Hot",
        //  "DatesAvailable": [
        //    "2019-08-01T00:00:00",
        //    "2019-08-02T00:00:00"
        //  ],
        //  "TemperatureRanges": {
        //    "Cold": {
        //      "High": 20,
        //      "Low": -10
        //    },
        //    "Hot": {
        //      "High": 60,
        //      "Low": 20
        //    }
        //  }
        //}

        // Get value from a JsonNode.
        JsonNode temperatureNode = forecastNode!["Temperature"]!;
        Console.WriteLine($"Type={temperatureNode.GetType()}");
        Console.WriteLine($"JSON={temperatureNode.ToJsonString()}");
        //output:
        //Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement]
        //JSON = 25

        // Get a typed value from a JsonNode.
        int temperatureInt = (int)forecastNode!["Temperature"]!;
        Console.WriteLine($"Value={temperatureInt}");
        //output:
        //Value=25

        // Get a typed value from a JsonNode by using GetValue<T>.
        temperatureInt = forecastNode!["Temperature"]!.GetValue<int>();
        Console.WriteLine($"TemperatureInt={temperatureInt}");
        //output:
        //Value=25

        // Get a JSON object from a JsonNode.
        JsonNode temperatureRanges = forecastNode!["TemperatureRanges"]!;
        Console.WriteLine($"Type={temperatureRanges.GetType()}");
        Console.WriteLine($"JSON={temperatureRanges.ToJsonString()}");
        //output:
        //Type = System.Text.Json.Nodes.JsonObject
        //JSON = { "Cold":{ "High":20,"Low":-10},"Hot":{ "High":60,"Low":20} }

        // Get a JSON array from a JsonNode.
        JsonNode datesAvailable = forecastNode!["DatesAvailable"]!;
        Console.WriteLine($"Type={datesAvailable.GetType()}");
        Console.WriteLine($"JSON={datesAvailable.ToJsonString()}");
        //output:
        //datesAvailable Type = System.Text.Json.Nodes.JsonArray
        //datesAvailable JSON =["2019-08-01T00:00:00", "2019-08-02T00:00:00"]

        // Get an array element value from a JsonArray.
        JsonNode firstDateAvailable = datesAvailable[0]!;
        Console.WriteLine($"Type={firstDateAvailable.GetType()}");
        Console.WriteLine($"JSON={firstDateAvailable.ToJsonString()}");
        //output:
        //Type = System.Text.Json.Nodes.JsonValue`1[System.Text.Json.JsonElement]
        //JSON = "2019-08-01T00:00:00"

        // Get a typed value by chaining references.
        int coldHighTemperature = (int)forecastNode["TemperatureRanges"]!["Cold"]!["High"]!;
        Console.WriteLine($"TemperatureRanges.Cold.High={coldHighTemperature}");
        //output:
        //TemperatureRanges.Cold.High = 20

        // Parse a JSON array
        var datesNode = JsonNode.Parse(@"[""2019-08-01T00:00:00"",""2019-08-02T00:00:00""]");
        JsonNode firstDate = datesNode![0]!.GetValue<DateTime>();
        Console.WriteLine($"firstDate={ firstDate}");
        //output:
        //firstDate = "2019-08-01T00:00:00"
    }
}

*** 使用物件初始設定式建立 JsonNode DOM 並進行變更

下列範例顯示如何：
1. 使用物件初始設定式建立 DOM。
2. 對 DOM 進行變更。

using System.Text.Json;
using System.Text.Json.Nodes;

namespace JsonNodeFromObjectExample;

public class Program
{
    public static void Main()
    {
        // Create a new JsonObject using object initializers.
        var forecastObject = new JsonObject
        {
            ["Date"] = new DateTime(2019, 8, 1),
            ["Temperature"] = 25,
            ["Summary"] = "Hot",
            ["DatesAvailable"] = new JsonArray(
                new DateTime(2019, 8, 1), new DateTime(2019, 8, 2)),
            ["TemperatureRanges"] = new JsonObject
            {
                ["Cold"] = new JsonObject
                {
                    ["High"] = 20,
                    ["Low"] = -10
                }
            },
            ["SummaryWords"] = new JsonArray("Cool", "Windy", "Humid")
        };

        // Add an object.
        forecastObject!["TemperatureRanges"]!["Hot"] =
            new JsonObject { ["High"] = 60, ["Low"] = 20 };

        // Remove a property.
        forecastObject.Remove("SummaryWords");

        // Change the value of a property.
        forecastObject["Date"] = new DateTime(2019, 8, 3);

        var options = new JsonSerializerOptions { WriteIndented = true };
        Console.WriteLine(forecastObject.ToJsonString(options));
        //output:
        //{
        //  "Date": "2019-08-03T00:00:00",
        //  "Temperature": 25,
        //  "Summary": "Hot",
        //  "DatesAvailable": [
        //    "2019-08-01T00:00:00",
        //    "2019-08-02T00:00:00"
        //  ],
        //  "TemperatureRanges": {
        //    "Cold": {
        //      "High": 20,
        //      "Low": -10
        //    },
        //    "Hot": {
        //      "High": 60,
        //      "Low": 20
        //    }
        //  }
        //}
    }
}

*** 還原序列化 JSON 承載的子區段
下列範例示範如何使用 JsonNode 瀏覽至 JSON 樹狀結構的子區段，並從該子區段還原序列化單一值、自訂類型或陣列。
using System.Text.Json;
using System.Text.Json.Nodes;

namespace JsonNodePOCOExample;

public class TemperatureRanges : Dictionary<string, HighLowTemps>
{
}

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

public class Program
{
    public static DateTime[]? DatesAvailable { get; set; }

    public static void Main()
    {
        string jsonString = """
            {
              "Date": "2019-08-01T00:00:00",
              "Temperature": 25,
              "Summary": "Hot",
              "DatesAvailable": [
                "2019-08-01T00:00:00",
                "2019-08-02T00:00:00"
              ],
              "TemperatureRanges": {
                  "Cold": {
                      "High": 20,
                      "Low": -10
                  },
                  "Hot": {
                      "High": 60,
                      "Low": 20
                  }
              }
            }
            """;
        // Parse all of the JSON.
        JsonNode forecastNode = JsonNode.Parse(jsonString)!;

        // Get a single value
        int hotHigh = forecastNode["TemperatureRanges"]!["Hot"]!["High"]!.GetValue<int>();
        Console.WriteLine($"Hot.High={hotHigh}");
        // output:
        //Hot.High=60

        // Get a subsection and deserialize it into a custom type.
        JsonObject temperatureRangesObject = forecastNode!["TemperatureRanges"]!.AsObject();
        using var stream = new MemoryStream();
        using var writer = new Utf8JsonWriter(stream);
        temperatureRangesObject.WriteTo(writer);
        writer.Flush();
        TemperatureRanges? temperatureRanges = 
            JsonSerializer.Deserialize<TemperatureRanges>(stream.ToArray());
        Console.WriteLine($"Cold.Low={temperatureRanges!["Cold"].Low}, Hot.High={temperatureRanges["Hot"].High}");
        // output:
        //Cold.Low=-10, Hot.High=60

        // Get a subsection and deserialize it into an array.
        JsonArray datesAvailable = forecastNode!["DatesAvailable"]!.AsArray()!;
        Console.WriteLine($"DatesAvailable[0]={datesAvailable[0]}");
        // output:
        //DatesAvailable[0]=8/1/2019 12:00:00 AM
    }
}

*** JsonNode 平均成績範例
下列範例會選取具有整數值的 JSON 陣列，並計算平均值：
using System.Text.Json.Nodes;

namespace JsonNodeAverageGradeExample;

public class Program
{
    public static void Main()
    {
        string jsonString = """
            {
              "Class Name": "Science",
              "Teacher\u0027s Name": "Jane",
              "Semester": "2019-01-01",
              "Students": [
                {
                  "Name": "John",
                  "Grade": 94.3
                },
                {
                  "Name": "James",
                  "Grade": 81.0
                },
                {
                  "Name": "Julia",
                  "Grade": 91.9
                },
                {
                  "Name": "Jessica",
                  "Grade": 72.4
                },
                {
                  "Name": "Johnathan"
                }
              ],
              "Final": true
            }
            """;
        double sum = 0;
        JsonNode document = JsonNode.Parse(jsonString)!;

        JsonNode root = document.Root;
        JsonArray studentsArray = root["Students"]!.AsArray();

        int count = studentsArray.Count;
        foreach (JsonNode? student in studentsArray)
        {
            if (student?["Grade"] is JsonNode gradeNode)
            {
                sum += (double)gradeNode;
            }
            else
            {
                sum += 70;
            }
        }

        double average = sum / count;
        Console.WriteLine($"Average grade : {average}");
    }
}
// output:
//Average grade : 81.92
上述 程式碼：
1. 計算具有 Grade 屬性之 Students 陣列中物件的平均成績。
2. 為沒有分數的學生指派預設的 70 分成績。
3. 從 JsonArray 的 Count 屬性取得學生數目。

*** 包含 JsonSerializerOptions 的 JsonNode
您可以使用 JsonSerializer 來序列化和還原序列化 JsonNode 的執行個體。 
不過，如果您使用採用 JsonSerializerOptions 的多載，則選項執行個體只會用來取得自訂轉換器。 
系統不會使用選項執行個體的其他功能。 
例如，如果您將 JsonSerializerOptions.DefaultIgnoreCondition 設定為 WhenWritingNull，並使用採用 JsonSerializerOptions 的多載呼叫 JsonSerializer，則不會忽略 null 屬性。

相同的限制適用於採用 JsonSerializerOptions 參數的 JsonNode 方法：
WriteTo(Utf8JsonWriter, JsonSerializerOptions) 和 ToJsonString(JsonSerializerOptions)。 
這些 API 只會使用 JsonSerializerOptions 來取得自訂轉換器。

下列範例說明使用採用 JsonSerializerOptions 參數並序列化 JsonNode 執行個體的方法結果：
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
using System.Text.Json.Serialization;

namespace JsonNodeWithJsonSerializerOptions;

public class Program
{
    public static void Main()
    {
        Person person = new() { Name = "Nancy" };

        // Default serialization - Address property included with null token.
        // Output: {"Name":"Nancy","Address":null}
        string personJsonWithNull = JsonSerializer.Serialize(person);
        Console.WriteLine(personJsonWithNull);

        // Serialize and ignore null properties - null Address property is omitted
        // Output: {"Name":"Nancy"}
        JsonSerializerOptions options = new()
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        };
        string personJsonWithoutNull = JsonSerializer.Serialize(person, options);
        Console.WriteLine(personJsonWithoutNull);

        // Ignore null properties doesn't work when serializing JsonNode instance
        // by using JsonSerializer.
        // Output: {"Name":"Nancy","Address":null}
        JsonNode? personJsonNode = JsonSerializer.Deserialize<JsonNode>(personJsonWithNull);
        personJsonWithNull = JsonSerializer.Serialize(personJsonNode, options);
        Console.WriteLine(personJsonWithNull);

        // Ignore null properties doesn't work when serializing JsonNode instance
        // by using JsonNode.ToJsonString method.
        // Output: {"Name":"Nancy","Address":null}
        personJsonWithNull = personJsonNode!.ToJsonString(options);
        Console.WriteLine(personJsonWithNull);

        // Ignore null properties doesn't work when serializing JsonNode instance
        // by using JsonNode.WriteTo method.
        // Output: {"Name":"Nancy","Address":null}
        using var stream = new MemoryStream();
        using var writer = new Utf8JsonWriter(stream);
        personJsonNode!.WriteTo(writer, options);
        writer.Flush();
        personJsonWithNull = Encoding.UTF8.GetString(stream.ToArray());
        Console.WriteLine(personJsonWithNull);
    }
}

public class Person
{
    public string? Name { get; set; }
    public string? Address { get; set; }
}
如果您需要自訂轉換器以外的 JsonSerializerOptions 功能，請使用 JsonSerializer 搭配強型別目標 (例如此範例中的 Person 類別) 而非 JsonNode。

*** 使用 JsonDocument

下列範例示範如何使用 JsonDocument 類別來隨機存取 JSON 字串中的資料：

double sum = 0;
int count = 0;

using (JsonDocument document = JsonDocument.Parse(jsonString))
{
    JsonElement root = document.RootElement;
    JsonElement studentsElement = root.GetProperty("Students");
    foreach (JsonElement student in studentsElement.EnumerateArray())
    {
        if (student.TryGetProperty("Grade", out JsonElement gradeElement))
        {
            sum += gradeElement.GetDouble();
        }
        else
        {
            sum += 70;
        }
        count++;
    }
}

double average = sum / count;
Console.WriteLine($"Average grade : {average}");

上述 程式碼：
1. 假設要分析的 JSON 位於名為 jsonString 的字串中。
2. 計算具有 Grade 屬性之 Students 陣列中物件的平均成績。
3. 為沒有分數的學生指派預設的 70 分成績。
4. 因為 JsonDocument 會實作 IDisposable，所以請在 using 陳述式中建立 JsonDocument 執行個體。 
處置 JsonDocument 執行個體之後，您也會失去其所有 JsonElement 執行個體的存取權。 
若要保留 JsonElement 執行個體的存取權，請在處置父 JsonDocument 執行個體之前，先建立其複本。 
若要建立複本，請呼叫 JsonElement.Clone。 
如需詳細資訊，請參閱 JsonDocument 為 IDisposable。

上述範例程式碼會藉由遞增每個反覆項目的 count 變數來計算學生。 
替代方法是呼叫 GetArrayLength，如下列範例所示：
double sum = 0;
int count = 0;

using (JsonDocument document = JsonDocument.Parse(jsonString))
{
    JsonElement root = document.RootElement;
    JsonElement studentsElement = root.GetProperty("Students");

    count = studentsElement.GetArrayLength();

    foreach (JsonElement student in studentsElement.EnumerateArray())
    {
        if (student.TryGetProperty("Grade", out JsonElement gradeElement))
        {
            sum += gradeElement.GetDouble();
        }
        else
        {
            sum += 70;
        }
    }
}

double average = sum / count;
Console.WriteLine($"Average grade : {average}");

下列是此程式碼所處理 JSON 的範例：
{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

*** 如何搜尋 JsonDocument 與 JsonElement 以尋找子元素
因為 JsonElement 搜尋需要循序搜尋屬性，所以相對緩慢 (例如使用 TryGetProperty 時)。 
System.Text.Json 的設計目的是將初始剖析時間降至最低，而不是查閱時間。 
因此，在搜尋 JsonDocument 物件時，請使用下列方法來最佳化效能：

1. 使用內建列舉程式 (EnumerateArray 和 EnumerateObject)，而非執行您自己的索引或迴圈。
2. 請勿透過使用 RootElement 在整個 JsonDocument 上循序搜尋每個屬性。 
相反地，請根據 JSON 資料的已知結構來搜尋巢狀 JSON 物件。 
例如，上述程式碼範例會藉由在 Student 物件之間執行迴圈並取得每個物件的 Grade 值來尋找 Student 物件中的 Grade 屬性，而非搜尋所有 JsonElement 物件來尋找 Grade 屬性。 
執行後者會導致不必要地傳遞相同的資料。

*** 使用 JsonDocument 來撰寫 JSON
下列範例示範如何從 JsonDocument 撰寫 JSON：
string jsonString = File.ReadAllText(inputFileName);

var writerOptions = new JsonWriterOptions
{
    Indented = true
};

var documentOptions = new JsonDocumentOptions
{
    CommentHandling = JsonCommentHandling.Skip
};

using FileStream fs = File.Create(outputFileName);
using var writer = new Utf8JsonWriter(fs, options: writerOptions);
using JsonDocument document = JsonDocument.Parse(jsonString, documentOptions);

JsonElement root = document.RootElement;

if (root.ValueKind == JsonValueKind.Object)
{
    writer.WriteStartObject();
}
else
{
    return;
}

foreach (JsonProperty property in root.EnumerateObject())
{
    property.WriteTo(writer);
}

writer.WriteEndObject();

writer.Flush();
上述 程式碼：
1. 讀取 JSON 檔案、將資料載入至 JsonDocument，並將格式化的 (已調整格式) JSON 寫入檔案。
2. 使用 JsonDocumentOptions 來指定輸入 JSON 中允許但會被忽略的註解。
3. 完成時，在寫入器上呼叫 Flush。 替代方法是讓寫入器在受到處置時自動排清。

下列是範例程式碼所要處理的 JSON 輸入範例：
{"Class Name": "Science","Teacher's Name": "Jane","Semester": "2019-01-01","Students": [{"Name": "John","Grade": 94.3},{"Name": "James","Grade": 81.0},{"Name": "Julia","Grade": 91.9},{"Name": "Jessica","Grade": 72.4},{"Name": "Johnathan"}],"Final": true}

結果是下列已調整格式的 JSON 輸出：
{
  "Class Name": "Science",
  "Teacher\u0027s Name": "Jane",
  "Semester": "2019-01-01",
  "Students": [
    {
      "Name": "John",
      "Grade": 94.3
    },
    {
      "Name": "James",
      "Grade": 81.0
    },
    {
      "Name": "Julia",
      "Grade": 91.9
    },
    {
      "Name": "Jessica",
      "Grade": 72.4
    },
    {
      "Name": "Johnathan"
    }
  ],
  "Final": true
}

*** JsonDocument 為 IDisposable
JsonDocument 會將資料的記憶體內部檢視建置到集區緩衝區中。 
因此，JsonDocument 類型會實作 IDisposable，且必須在 using 區塊內使用。

只有在您想要移轉存留期擁有權並處置呼叫端的責任時，才會從您的 API 傳回 JsonDocument。 在大部分情況下，這並非必要。 
如果呼叫端需要使用整個 JSON 文件，則會傳回 RootElement 的 Clone，也就是 JsonElement。 
如果呼叫端需要使用 JSON 文件內的特定元素，則會傳回該 JsonElement 的 Clone。 
如果您直接傳回 RootElement 或子元素，而非發出 Clone，則呼叫端將無法在處置擁有傳回項目的 JsonDocument 之後，存取其傳回的 JsonElement。

下列是要求您發出 Clone 的範例：
public JsonElement LookAndLoad(JsonElement source)
{
    string json = File.ReadAllText(source.GetProperty("fileName").GetString());

    using (JsonDocument doc = JsonDocument.Parse(json))
    {
        return doc.RootElement.Clone();
    }
}
上述程式碼預期包含 fileName 屬性的 JsonElement。 其會開啟 JSON 檔案並建立 JsonDocument。 因為該方法假設呼叫端想要使用整個文件，所以會傳回 RootElement 的 Clone。

如果您收到 JsonElement 並傳回子元素，則不需要傳回子元素的 Clone。 呼叫端負責讓傳入 JsonElement 所屬的 JsonDocument 保持運作。 例如：
public JsonElement ReturnFileName(JsonElement source)
{
   return source.GetProperty("fileName");
}

*** 包含 JsonSerializerOptions 的 JsonDocument
您可以使用 JsonSerializer 來序列化和還原序列化 JsonDocument 的執行個體。 不過，使用 JsonSerializer 來讀取和寫入 JsonDocument 執行個體的實作是 JsonDocument.ParseValue(Utf8JsonReader) 和 JsonDocument.WriteTo(Utf8JsonWriter) 的包裝函式。 此包裝函式不會將任何 JsonSerializerOptions (序列化程式功能) 轉接至 Utf8JsonReader 或 Utf8JsonWriter。 例如，如果您將 JsonSerializerOptions.DefaultIgnoreCondition 設定為 WhenWritingNull，並使用採用 JsonSerializerOptions 的多載呼叫 JsonSerializer，則不會忽略 null 屬性。

下列範例說明使用採用 JsonSerializerOptions 參數並序列化 JsonDocument 執行個體的方法結果：
using System.Text.Json;
using System.Text.Json.Serialization;

namespace JsonDocumentWithJsonSerializerOptions;

public class Program
{
    public static void Main()
    {
        Person person = new() { Name = "Nancy" };

        // Default serialization - Address property included with null token.
        // Output: {"Name":"Nancy","Address":null}
        string personJsonWithNull = JsonSerializer.Serialize(person);
        Console.WriteLine(personJsonWithNull);

        // Serialize and ignore null properties - null Address property is omitted
        // Output: {"Name":"Nancy"}
        JsonSerializerOptions options = new()
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        };
        string personJsonWithoutNull = JsonSerializer.Serialize(person, options);
        Console.WriteLine(personJsonWithoutNull);

        // Ignore null properties doesn't work when serializing JsonDocument instance
        // by using JsonSerializer.
        // Output: {"Name":"Nancy","Address":null}
        JsonDocument? personJsonDocument = JsonSerializer.Deserialize<JsonDocument>(personJsonWithNull);
        personJsonWithNull = JsonSerializer.Serialize(personJsonDocument, options);
        Console.WriteLine(personJsonWithNull);
    }
}
public class Person
{
    public string? Name { get; set; }
    public string? Address { get; set; }
}
如果您需要 JsonSerializerOptions 的功能，請使用 JsonSerializer 搭配強型別目標 (例如此範例中的 Person 類別) 而非 JsonDocument。


**** 使用 Utf8JsonWriter
如何在 System.Text.Json 中使用 Utf8JsonWriter
Utf8JsonWriter 是一種高效能方式，可從常見的 .NET 類型 (例如 String、Int32 與 DateTime) 撰寫 UTF-8 編碼的 JSON 文字。 
寫入器是一個低階類型，可用於建置自訂序列化程式。 
實際上，JsonSerializer.Serialize 方法會使用 Utf8JsonWriter。

*** 下列範例將示範如何使用 Utf8JsonWriter 類別：
var options = new JsonWriterOptions
{
    Indented = true
};

using var stream = new MemoryStream();
using var writer = new Utf8JsonWriter(stream, options);

writer.WriteStartObject();
writer.WriteString("date", DateTimeOffset.UtcNow);
writer.WriteNumber("temp", 42);
writer.WriteEndObject();
writer.Flush();

string json = Encoding.UTF8.GetString(stream.ToArray());
Console.WriteLine(json);

*** 使用 UTF-8 文字撰寫
若要在使用 Utf8JsonWriter 時達到最佳效能，請撰寫已編碼為 UTF-8 文字的 JSON 承載，而非 UTF-16 字串。 
使用 JsonEncodedText 快取並預先編碼已知的字串屬性名稱和值作為靜態，並將這些名稱和值傳遞至寫入器，而非使用 UTF-16 字串常值。 
這比快取和使用 UTF-8 位元組陣列更快。

如果您需要執行自訂逸出，此方法也適用。 
System.Text.Json 不會讓您在撰寫字串時停用逸出。 
不過，您可以將自己的自訂 JavaScriptEncoder 作為選項傳遞至寫入器，或建立自己的 JsonEncodedText，以使用您的 JavascriptEncoder 來執行逸出，然後寫入 JsonEncodedText 而非字串。 
如需詳細資訊，請參閱自訂字元編碼。

*** 撰寫原始 JSON
在某些情況下，您可能會想要將「原始」JSON 寫入您正在使用 Utf8JsonWriter 建立的 JSON 承載。 
您可以使用 Utf8JsonWriter.WriteRawValue 來執行此作業。 
以下是典型案例：
1. 您有想要以新 JSON 括住的現有 JSON 承載。
2. 您想要將值設定為不同於預設 Utf8JsonWriter 格式設定的格式。

例如，您可能想要自訂數字格式設定。 根據預設，System.Text.Json 會省略整數的小數點；例如，寫入 1 而非 1.0。 
其理由是寫入較少的位元組有益效能。 
但假設 JSON 的取用者會將具有小數的數字視為雙精度浮點數，而不含小數點的數字則視為整數。 
建議您藉由撰寫整數的小數點和零，確保陣列中的數字全都辨識為雙精度浮點數。 
下列範例顯示如何執行該項工作：
using System.Text;
using System.Text.Json;

namespace WriteRawJson;

public class Program
{
    public static void Main()
    {
        JsonWriterOptions writerOptions = new() { Indented = true, };

        using MemoryStream stream = new();
        using Utf8JsonWriter writer = new(stream, writerOptions);

        writer.WriteStartObject();

        writer.WriteStartArray("defaultJsonFormatting");
        foreach (double number in new double[] { 50.4, 51 })
        {
            writer.WriteStartObject();
            writer.WritePropertyName("value");
            writer.WriteNumberValue(number);
            writer.WriteEndObject();
        }
        writer.WriteEndArray();

        writer.WriteStartArray("customJsonFormatting");
        foreach (double result in new double[] { 50.4, 51 })
        {
            writer.WriteStartObject();
            writer.WritePropertyName("value");
            writer.WriteRawValue(
                FormatNumberValue(result), skipInputValidation: true);
            writer.WriteEndObject();
        }
        writer.WriteEndArray();

        writer.WriteEndObject();
        writer.Flush();

        string json = Encoding.UTF8.GetString(stream.ToArray());
        Console.WriteLine(json);
    }
    static string FormatNumberValue(double numberValue)
    {
        return numberValue == Convert.ToInt32(numberValue) ? 
            numberValue.ToString() + ".0" : numberValue.ToString();
    }
}
// output:
//{
//  "defaultJsonFormatting": [
//    {
//      "value": 50.4
//    },
//    {
//      "value": 51
//    }
//  ],
//  "customJsonFormatting": [
//    {
//      "value": 50.4
//    },
//    {
//      "value": 51.0
//    }
//  ]
//}

*** 自訂字元逸出
JsonTextWriter 的 StringEscapeHandling 設定提供逸出所有非 ASCII 字元或 HTML 字元的選項。 根據預設，Utf8JsonWriter 會逸出所有非 ASCII 和 HTML 字元。 此逸出是為了深層防禦安全性理由而進行的。 若要指定不同的逸出原則，請建立 JavaScriptEncoder 並設定 JsonWriterOptions.Encoder。 如需詳細資訊，請參閱自訂字元編碼。

*** 撰寫 null 值
若要使用 Utf8JsonWriter 撰寫 null 值，請呼叫：
WriteNull 以將機碼值組寫入 null 作為值。
WriteNullValue 以將 null 寫入為 JSON 陣列的元素。

針對字串屬性，如果字串為 null，則 WriteString 和 WriteStringValue 相當於 WriteNull 和 WriteNullValue。

*** 撰寫 Timespan、URI 或 char 值
若要撰寫 Timespan、Uri、或 char 值，請將其格式化為字串 (例如藉由呼叫 ToString()) 並呼叫 WriteStringValue。



**** 使用 Utf8JsonReader
如何在 System.Text.Json 中使用 Utf8JsonReader

本文示範如何使用 Utf8JsonReader 類型來建置自訂剖析器和還原序列化程式。

Utf8JsonReader 是一個高效能、低配置、只能順向讀取的 UTF-8 編碼 JSON 文字讀取器，其會從 ReadOnlySpan<byte> 或 ReadOnlySequence<byte> 開始讀取。 Utf8JsonReader 是一個低階類型，可用於建置自訂剖析器與還原序列化程式。 JsonSerializer.Deserialize 方法在涵蓋範圍下使用 Utf8JsonReader。

Utf8JsonReader 無法直接從 Visual Basic 程式碼使用。 如需詳細資訊，請參閱 Visual Basic 支援。

下列範例將示範如何使用 Utf8JsonReader 類別：
var options = new JsonReaderOptions
{
    AllowTrailingCommas = true,
    CommentHandling = JsonCommentHandling.Skip
};
var reader = new Utf8JsonReader(jsonUtf8Bytes, options);

while (reader.Read())
{
    Console.Write(reader.TokenType);

    switch (reader.TokenType)
    {
        case JsonTokenType.PropertyName:
        case JsonTokenType.String:
            {
                string? text = reader.GetString();
                Console.Write(" ");
                Console.Write(text);
                break;
            }

        case JsonTokenType.Number:
            {
                int intValue = reader.GetInt32();
                Console.Write(" ");
                Console.Write(intValue);
                break;
            }

            // Other token types elided for brevity
    }
    Console.WriteLine();
}

上述程式碼假設 jsonUtf8 變數是位元組陣列，其中包含編碼為 UTF-8 的有效 JSON。

*** 使用 Utf8JsonReader 篩選資料
下列範例示範如何同步讀取檔案並搜尋值。
using System.Text;
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class Utf8ReaderFromFile
    {
        private static readonly byte[] s_nameUtf8 = Encoding.UTF8.GetBytes("name");
        private static ReadOnlySpan<byte> Utf8Bom => new byte[] { 0xEF, 0xBB, 0xBF };

        public static void Run()
        {
            // ReadAllBytes if the file encoding is UTF-8:
            string fileName = "UniversitiesUtf8.json";
            ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);

            // Read past the UTF-8 BOM bytes if a BOM exists.
            if (jsonReadOnlySpan.StartsWith(Utf8Bom))
            {
                jsonReadOnlySpan = jsonReadOnlySpan.Slice(Utf8Bom.Length);
            }

            // Or read as UTF-16 and transcode to UTF-8 to convert to a ReadOnlySpan<byte>
            //string fileName = "Universities.json";
            //string jsonString = File.ReadAllText(fileName);
            //ReadOnlySpan<byte> jsonReadOnlySpan = Encoding.UTF8.GetBytes(jsonString);

            int count = 0;
            int total = 0;

            var reader = new Utf8JsonReader(jsonReadOnlySpan);

            while (reader.Read())
            {
                JsonTokenType tokenType = reader.TokenType;

                switch (tokenType)
                {
                    case JsonTokenType.StartObject:
                        total++;
                        break;
                    case JsonTokenType.PropertyName:
                        if (reader.ValueTextEquals(s_nameUtf8))
                        {
                            // Assume valid JSON, known schema
                            reader.Read();
                            if (reader.GetString()!.EndsWith("University"))
                            {
                                count++;
                            }
                        }
                        break;
                }
            }
            Console.WriteLine($"{count} out of {total} have names that end with 'University'");
        }
    }
}

如需此範例的非同步版本，請參閱 .NET 範例 JSON 專案。

上述 程式碼：

假設 JSON 包含物件的陣列，且每個物件可能包含類型字串的 "name" 屬性。

計算以 "University" 結尾的物件和 "name" 屬性值。

假設檔案編碼為 UTF-16，並將其轉碼為 UTF-8。 編碼為 UTF-8 的檔案可以使用下列程式碼直接讀取至 ReadOnlySpan<byte>：

ReadOnlySpan<byte> jsonReadOnlySpan = File.ReadAllBytes(fileName);

如果檔案包含 UTF-8 位元組順序標記 (BOM)，請先將其移除，再將位元組傳遞至 Utf8JsonReader，因為讀取器預期文字。 否則，BOM 會被視為無效 JSON，而讀取器會擲回例外狀況。

下列是上述程式碼可讀取的 JSON 範例。 所產生摘要訊息為「4 個中有 2 個名稱的結尾為 'University'」：
[
  {
    "web_pages": [ "https://contoso.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contoso.edu" ],
    "name": "Contoso Community College"
  },
  {
    "web_pages": [ "http://fabrikam.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikam.edu" ],
    "name": "Fabrikam Community College"
  },
  {
    "web_pages": [ "http://www.contosouniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "contosouniversity.edu" ],
    "name": "Contoso University"
  },
  {
    "web_pages": [ "http://www.fabrikamuniversity.edu/" ],
    "alpha_two_code": "US",
    "state-province": null,
    "country": "United States",
    "domains": [ "fabrikamuniversity.edu" ],
    "name": "Fabrikam University"
  }
]

*** 使用讀取 Utf8JsonReader 串流
讀取大型檔案 (例如 GB 或更大的大小時)，建議您避免一次將整個檔案載入記憶體。 針對此案例，您可以使用 FileStream。

使用 Utf8JsonReader 讀取串流時，適用下列規則：

1. 包含部分 JSON 承載的緩衝區至少必須與其中最大的 JSON 權杖一樣大，以便讀取器可以推展進度。
2. 緩衝區必須至少與 JSON 內的最大空白字元序列一樣大。
3. 讀取器不會追蹤其讀取的資料，直到其完全讀取 JSON 承載中的下一個 TokenType 為止。 
因此，當緩衝區中有剩餘的位元組時，您必須再次將其傳遞至讀取器。 
您可以使用 BytesConsumed 來判斷剩餘的位元組數目。

下列程式碼說明如何讀取串流。 此範例顯示 MemoryStream。 
類似的程式碼會搭配使用 FileStream，但在 FileStream 的開頭包含 UTF-8 BOM 時除外。 
在此情況下，您必須先從緩衝區移除這三個位元組，再將剩餘位元組傳遞至 Utf8JsonReader。 
否則，因為 BOM 不會被視為 JSON 的有效部分，所以讀取器會擲回例外狀況。

範例程式碼會從 4 KB 緩衝區開始，並在每次發現大小不足以符合完整的 JSON 權杖時，將緩衝區的大小加倍，這是讀取器在 JSON 承載上推展進度時的必要作業。 
只有在您設定非常小的初始緩衝區大小 (例如 10 個位元組) 時，程式碼片段中提供的 JSON 範例才會觸發緩衝區大小增加。 
如果您將初始緩衝區大小設定為 10，則 Console.WriteLine 陳述式會說明緩衝區大小增加的原因和效果。 
在 4 KB 初始緩衝區大小上，每個 Console.WriteLine 都會顯示整個範例 JSON，且緩衝區大小永遠都不需要增加。

using System.Text;
using System.Text.Json;

namespace SystemTextJsonSamples
{
    public class Utf8ReaderPartialRead
    {
        public static void Run()
        {
            var jsonString = @"{
                ""Date"": ""2019-08-01T00:00:00-07:00"",
                ""Temperature"": 25,
                ""TemperatureRanges"": {
                    ""Cold"": { ""High"": 20, ""Low"": -10 },
                    ""Hot"": { ""High"": 60, ""Low"": 20 }
                },
                ""Summary"": ""Hot"",
            }";

            byte[] bytes = Encoding.UTF8.GetBytes(jsonString);
            var stream = new MemoryStream(bytes);

            var buffer = new byte[4096];

            // Fill the buffer.
            // For this snippet, we're assuming the stream is open and has data.
            // If it might be closed or empty, check if the return value is 0.
            stream.Read(buffer);

            // We set isFinalBlock to false since we expect more data in a subsequent read from the stream.
            var reader = new Utf8JsonReader(buffer, isFinalBlock: false, state: default);
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");

            // Search for "Summary" property name
            while (reader.TokenType != JsonTokenType.PropertyName || !reader.ValueTextEquals("Summary"))
            {
                if (!reader.Read())
                {
                    // Not enough of the JSON is in the buffer to complete a read.
                    GetMoreBytesFromStream(stream, ref buffer, ref reader);
                }
            }

            // Found the "Summary" property name.
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");
            while (!reader.Read())
            {
                // Not enough of the JSON is in the buffer to complete a read.
                GetMoreBytesFromStream(stream, ref buffer, ref reader);
            }
            // Display value of Summary property, that is, "Hot".
            Console.WriteLine($"Got property value: {reader.GetString()}");
        }

        private static void GetMoreBytesFromStream(
            MemoryStream stream, ref byte[] buffer, ref Utf8JsonReader reader)
        {
            int bytesRead;
            if (reader.BytesConsumed < buffer.Length)
            {
                ReadOnlySpan<byte> leftover = buffer.AsSpan((int)reader.BytesConsumed);

                if (leftover.Length == buffer.Length)
                {
                    Array.Resize(ref buffer, buffer.Length * 2);
                    Console.WriteLine($"Increased buffer size to {buffer.Length}");
                }

                leftover.CopyTo(buffer);
                bytesRead = stream.Read(buffer.AsSpan(leftover.Length));
            }
            else
            {
                bytesRead = stream.Read(buffer);
            }
            Console.WriteLine($"String in buffer is: {Encoding.UTF8.GetString(buffer)}");
            reader = new Utf8JsonReader(buffer, isFinalBlock: bytesRead == 0, reader.CurrentState);
        }
    }
}


上述範例不會設定緩衝區成長大小的限制。 如果權杖大小過大，則程式碼可能會失敗，並發生 OutOfMemoryException 例外狀況。 
因為 1 GB 大小加倍會導致大小過大而無法放入 int32 緩衝區，所以如果 JSON 包含大約 1 GB 或更大的權杖，就會發生這種情況。

*** ref 結構限制
因為 Utf8JsonReader 類型是 ref 結構，所以具有特定限制。 例如，其無法儲存為 ref 結構以外類別或結構上的欄位。

若要達到高效能，此類型必須是 ref struct，因為其需要快取輸入 ReadOnlySpan<byte>，而這本身為 ref 結構。 此外，Utf8JsonReader 類型是可變的，因為其會保留狀態。 因此，請以傳址方式傳遞，而非依值傳遞。 依值傳遞會導致結構複本，且呼叫端看不到狀態變更。

如需如何使用 ref 結構的詳細資訊，請參閱避免配置。


*** 讀取 UTF-8 文字
若要在使用 Utf8JsonReader 時達到最佳效能，請讀取已編碼為 UTF-8 文字的 JSON 承載，而非 UTF-16 字串。 如需程式碼範例，請參閱使用 Utf8JsonReader 篩選資料。

*** 使用多區段 ReadOnlySequence 讀取
如果您的 JSON 輸入是 ReadOnlySpan<byte>，當您執行讀取迴圈時，可以在讀取器上從 ValueSpan 屬性存取每個 JSON 元素。 不過，如果您的輸入是 ReadOnlySequence<byte> (這是從 PipeReader 讀取的結果)，則部分 JSON 元素可能會跨越 ReadOnlySequence<byte> 物件的多個區段。 這些元素無法從連續記憶體區塊中的 ValueSpan 存取。 相反地，每當您使用多區段 ReadOnlySequence<byte> 作為輸入時，請輪詢讀取器上的 HasValueSequence 屬性，以找出存取目前 JSON 元素的方法。 下列是建議的模式：

while (reader.Read())
{
    switch (reader.TokenType)
    {
        // ...
        ReadOnlySpan<byte> jsonElement = reader.HasValueSequence ?
            reader.ValueSequence.ToArray() :
            reader.ValueSpan;
        // ...
    }
}

*** 針對屬性名稱查閱使用 ValueTextEquals
請勿透過呼叫 SequenceEqual 執行屬性名稱查閱來使用 ValueSpan 執行逐一位元組比較。 因為呼叫 ValueTextEquals 會取消逸出 JSON 中逸出的任何字元，所以請改為使用該方法。 下列範例示範如何搜尋名為 "named" 的屬性：
private static readonly byte[] s_nameUtf8 = Encoding.UTF8.GetBytes("name");
while (reader.Read())
{
    switch (reader.TokenType)
    {
        case JsonTokenType.StartObject:
            total++;
            break;
        case JsonTokenType.PropertyName:
            if (reader.ValueTextEquals(s_nameUtf8))
            {
                count++;
            }
            break;
    }
}

*** 將 null 值讀入可為 Null 的實值型別
內建 System.Text.Json API 只會傳回不可為 Null 的實值型別。 例如，Utf8JsonReader.GetBoolean 會傳回 bool。 如果在 JSON 中找到 Null，則會擲回例外狀況。 下列範例示範兩種處理 null 的方法，一種是傳回可為 Null 的實值型別，另一種是傳回預設值：
public bool? ReadAsNullableBoolean()
{
    _reader.Read();
    if (_reader.TokenType == JsonTokenType.Null)
    {
        return null;
    }
    if (_reader.TokenType != JsonTokenType.True && _reader.TokenType != JsonTokenType.False)
    {
        throw new JsonException();
    }
    return _reader.GetBoolean();
}

public bool ReadAsBoolean(bool defaultValue)
{
    _reader.Read();
    if (_reader.TokenType == JsonTokenType.Null)
    {
        return defaultValue;
    }
    if (_reader.TokenType != JsonTokenType.True && _reader.TokenType != JsonTokenType.False)
    {
        throw new JsonException();
    }
    return _reader.GetBoolean();
}


*** 跳過權杖的子系
使用 Utf8JsonReader.Skip() 方法跳過目前 JSON 權杖的子系。 如果權杖類型為 JsonTokenType.PropertyName，讀取器會移至屬性值。 下列程式碼片段示範使用 Utf8JsonReader.Skip() 將讀取器移至屬性值的範例。

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

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

var reader = new Utf8JsonReader(jsonUtf8Bytes);

int temp;
while (reader.Read())
{
    switch (reader.TokenType)
    {
        case JsonTokenType.PropertyName:
            {
                if (reader.ValueTextEquals("TemperatureCelsius"))
                {
                    reader.Skip();
                    temp = reader.GetInt32();

                    Console.WriteLine($"Temperature is {temp} degrees.");
                }
                continue;
            }
        default:
            continue;
    }
}

*** 取用解碼的 JSON 字串
從 .NET 7 開始，您可以使用 Utf8JsonReader.CopyString 方法而非 Utf8JsonReader.GetString() 來取用解碼的 JSON 字串。 不同於 GetString() 一律會配置新字串的，CopyString 可讓您將未逸出的字串複製到您擁有的緩衝區。 下列程式碼片段顯示使用 CopyString 來取用 UTF-16 字串的範例。

var reader = new Utf8JsonReader( /* jsonReadOnlySpan */ );

int valueLength = reader.HasValueSequence
    ? checked((int)reader.ValueSequence.Length)
    : reader.ValueSpan.Length;

char[] buffer = ArrayPool<char>.Shared.Rent(valueLength);
int charsRead = reader.CopyString(buffer);
ReadOnlySpan<char> source = buffer.AsSpan(0, charsRead);

// Handle the unescaped JSON string.
ParseUnescapedString(source);
ArrayPool<char>.Shared.Return(buffer, clearArray: true);

void ParseUnescapedString(ReadOnlySpan<char> source)
{
    // ...
}

*** 相關的 API
1. 若要從 Utf8JsonReader 執行個體還原序列化自訂類型，請呼叫 JsonSerializer.Deserialize<TValue>(Utf8JsonReader, JsonSerializerOptions) 或 JsonSerializer.Deserialize<TValue>(Utf8JsonReader, JsonTypeInfo<TValue>)。 如需範例，請參閱從 UTF-8 還原串行化。

2. JsonNode 和從其衍生的類別提供了建立可變 DOM 的功能。 您可以呼叫 JsonNode.Parse(Utf8JsonReader, Nullable<JsonNodeOptions>)，將 Utf8JsonReader 執行個體轉換成 JsonNode。 下列程式碼片段為範例。
using System.Text.Json;
using System.Text.Json.Nodes;

namespace Utf8ReaderToJsonNode
{
    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"
            };

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

            var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
            JsonNode? node = JsonNode.Parse(ref utf8Reader);
            Console.WriteLine(node);
        }
    }
}using System.Text.Json;
using System.Text.Json.Nodes;

namespace Utf8ReaderToJsonNode
{
    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"
            };

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

            var utf8Reader = new Utf8JsonReader(jsonUtf8Bytes);
            JsonNode? node = JsonNode.Parse(ref utf8Reader);
            Console.WriteLine(node);
        }
    }
}
3. JsonDocument 提供使用 Utf8JsonReader 建置唯讀 DOM 的功能。 呼叫 JsonDocument.ParseValue(Utf8JsonReader) 方法，從 Utf8JsonReader 執行個體剖析 JsonDocument。 您可以透過 JsonElement 類型存取組成承載的 JSON 元素。 如需使用 JsonDocument.ParseValue(Utf8JsonReader) 的範例程式碼，請參閱 RoundtripDataTable.cs 和將推斷類型還原序列化為物件屬性中的程式碼片段。

4. 您也可以藉由呼叫 JsonElement.ParseValue(Utf8JsonReader)，將 Utf8JsonReader 執行個體剖析為 JsonElement，此執行個體代表特定的 JSON 值。