在序列化和還原序列化索引鍵/值組時，會接受 PropertyNamingPolicy、PropertyNameCaseInsensitive 和 Encoder 選項

  • 發行項

現在 JsonSerializer 在序列化 KeyValuePair<TKey,TValue> 執行個體的 Key 和 Value 屬性名稱時，會接受 PropertyNamingPolicy 和 Encoder 選項。 此外，在還原序列化 KeyValuePair<TKey,TValue> 執行個體時，JsonSerializer 會接受 PropertyNamingPolicy 和 PropertyNameCaseInsensitive 選項。

變更描述

序列化

在 .NET Core 3.x 版本和 System.Text.Json NuGet 套件的 4.6.0-4.7.2 版本中，KeyValuePair<TKey,TValue> 執行個體的屬性一律會完全序列化為「Key」和「Value」，不管任何 JsonSerializerOptions.PropertyNamingPolicy 和 JsonSerializerOptions.Encoder 選項為何。 下列程式碼範例顯示 Key 和 Value 屬性在序列化之後如何不會進行駝峰式大小寫，即使指定的屬性命名原則規定也一樣。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// Expected: {"key":1,"value":1}
// Actual: {"Key":1,"Value":1}

從 .NET 5 開始，序列 KeyValuePair<TKey,TValue> 化執行個體時會接受 PropertyNamingPolicy 和 Encoder 選項。 下列程式碼範例顯示 Key 和 Value 屬性在序列化之後如何進行駝峰式大小寫，與指定的屬性命名原則一致。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
KeyValuePair<int, int> kvp = KeyValuePair.Create(1, 1);
Console.WriteLine(JsonSerializer.Serialize(kvp, options));
// {"key":1,"value":1}

還原序列化

在 .NET Core 3.x 版本和 System.Text.Json NuGet 套件的 4.7.x 版本中，當 JSON 屬性名稱不是 Key 和 Value，像是如果未以大寫字母開頭，則會擲回 JsonException。 即使指定的屬性命名原則明確允許，也會擲回例外狀況。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";
// Throws JsonException.
JsonSerializer.Deserialize<KeyValuePair<int, int>>(json, options);

從 .NET 5 開始，使用 JsonSerializer 還原序列化時，會接受 PropertyNamingPolicy 和 PropertyNameCaseInsensitive 選項。 例如，下列程式碼片段顯示小寫 Key 和 Value 屬性名稱的成功還原序列化，因為指定的屬性命名原則允許它。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""key"":1,""value"":1}";

KeyValuePair<int, int> kvp = JsonSerializer.Deserialize<KeyValuePair<int, int>>(json);
Console.WriteLine(kvp.Key); // 1
Console.WriteLine(kvp.Value); // 1

為了容納以舊版序列化的承載，「Key」和「Value」會在還原序列化時符合特殊大小寫。 雖然 Key 和 Value 屬性名稱不是根據下列程式碼範例中的 PropertyNamingPolicy 選項進行駝峰式大小寫，但是仍會成功還原序列化。

var options = new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase };
string json = @"{""Key"":1,""Value"":1}";

KeyValuePair<int, int> kvp = JsonSerializer.Deserialize<KeyValuePair<int, int>>(json);
Console.WriteLine(kvp.Key); // 1
Console.WriteLine(kvp.Value); // 1

導入的版本

5.0

變更原因

大量客戶意見反應指出應接受 PropertyNamingPolicy。 為了完整起見，也會接受 PropertyNameCaseInsensitive 和 Encoder 選項，以便將 KeyValuePair<TKey,TValue> 執行個體視為與任何其他純舊 CLR 物件相同的 (POCO)。

如果這項變更對您造成干擾，您可以使用實作所需語意的自訂轉換器。

受影響的 API