.NET 6 中 System.Text.Json 的改进

01/05/2022 02:51:48 | China Standard Time

System.Text.Json 命名空间提供用于序列化和反序列化 JSON 的功能，它包含在 .NET Core 3.1 和更高的版本中。与 Newtonsoft.Json 不同，System.Text.Json 主要关注性能、安全性和标准符合性。这篇博客将会简单介绍一下微软在 .NET 6.0 中对 System.Text.Json 的改进内容。

## 忽略循环引用

在 .NET 5 中，如果检测到循环引用，会引发`JsonException`。在 .NET 6 中，你可以忽略循环引用。

```csharp
Category dotnet = new()
{
	Name = ".NET 6",
};
Category systemTextJson = new()
{
	Name = "System.Text.Json",
	Parent = dotnet
};
dotnet.Children.Add(systemTextJson);

JsonSerializerOptions options = new()
{
	ReferenceHandler = ReferenceHandler.IgnoreCycles,
	WriteIndented = true
};

string dotnetJson = JsonSerializer.Serialize(dotnet, options);
Console.WriteLine($"{dotnetJson}");

public class Category
{
	public string Name { get; set; }
	public Category Parent { get; set; }
	public List<Category> Children { get; set; } = new();
}

// Output:
// {
//   "Name": ".NET 6",
//   "Parent": null,
//   "Children": [
//     {
//       "Name": "System.Text.Json",
//       "Parent": null,
//       "Children": []
//     }
//   ]
// }
```

## 序列化和反序列化通知

在 .NET 6 中，你可以在序列化和反序列化时收到通知。

有四个新的接口可以根据需要来实现：
- IJsonOnDeserialized
- IJsonOnDeserializing
- IJsonOnSerialized
- IJsonOnSerializing

```csharp
Product invalidProduct = new() { Name = "Name", Test = "Test" };
JsonSerializer.Serialize(invalidProduct);
// The InvalidOperationException is thrown

string invalidJson = "{}";
JsonSerializer.Deserialize<Product>(invalidJson);
// The InvalidOperationException is thrown

class Product : IJsonOnDeserialized, IJsonOnSerializing, IJsonOnSerialized
{
	public string Name { get; set; }

	public string Test { get; set; }

	public void OnSerialized()
	{
		throw new NotImplementedException();
	}

	void IJsonOnDeserialized.OnDeserialized() => Validate(); // Call after deserialization
	void IJsonOnSerializing.OnSerializing() => Validate();   // Call before serialization

	private void Validate()
	{
		if (Name is null)
		{
			throw new InvalidOperationException("The 'Name' property cannot be 'null'.");
		}
	}
}
```

## 属性的序列化顺序

在 .NET 6 中，`JsonPropertyOrderAttribute`已添加到 System.Text.Json 中。它允许控制属性的序列化顺序。以前，序列化顺序由反射顺序确定。

```csharp
Product product = new()
{
	Id = 1,
	Name = "Surface Pro 7",
	Price = 550,
	Category = "Laptops"
};

JsonSerializerOptions options = new() { WriteIndented = true };
string json = JsonSerializer.Serialize(product, options);
Console.WriteLine(json);

class Product : A
{
	[JsonPropertyOrder(2)] // Serialize after Price
	public string Category { get; set; }

	[JsonPropertyOrder(1)] // Serialize after other properties that have default ordering
	public decimal Price { get; set; }

	public string Name { get; set; } // Has default ordering value of 0

	[JsonPropertyOrder(-1)] // Serialize before other properties that have default ordering
	public int Id { get; set; }
}

class A
{
	public int Test { get; set; }
}

// Output:
// {
//   "Id": 1,
//   "Name": "Surface Pro 7",
//   "Price": 550,
//   "Category": "Laptops"
// }
```

## 使用 Utf8JsonWriter 编写原始 JSON

.NET 6 引入了使用 System.Text.Json.Utf8JsonWriter 编写原始 JSON 的可能性。

使用场景：
- 将现有 JSON 包含在新的 JSON 中
- 设置不同于默认格式的值

```csharp
JsonWriterOptions writerOptions = new() { Indented = true, };

using MemoryStream stream = new();
using Utf8JsonWriter writer = new(stream, writerOptions);

writer.WriteStartObject();
writer.WriteStartArray("customJsonFormatting");
foreach (double result in new double[] { 10.2, 10 })
{
	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:
// {
//    "customJsonFormatting": [
//      {
//        "value": 10.2
//      },
//      {
//        "value": 10.0
//      }
//  ]
// }
```

## 异步枚举支持

在 .NET 6 中，System.Text.Json 支持`IAsyncEnumerable`。

```csharp
static async IAsyncEnumerable<int> GetNumbersAsync(int n)
{
	for (int i = 0; i < n; i++)
	{
		await Task.Delay(1000);
		yield return i;
	}
}
// Serialization using IAsyncEnumerable
JsonSerializerOptions options = new() { WriteIndented = true };
using Stream outputStream = Console.OpenStandardOutput();
var data = new { Data = GetNumbersAsync(5) };
await JsonSerializer.SerializeAsync(outputStream, data, options);
// Output:
// {
//    "Data": [
//      0,
//      1,
//      2,
//      3,
//      4
//  ]
// }

// Deserialization using IAsyncEnumerable
using MemoryStream memoryStream = new(Encoding.UTF8.GetBytes("[0,1,2,3,4]"));
// Wraps the UTF-8 encoded text into an IAsyncEnumerable<T> that can be used to deserialize root-level JSON arrays in a streaming manner.
await foreach (int item in JsonSerializer.DeserializeAsyncEnumerable<int>(memoryStream))
{
	Console.WriteLine(item);
}
// Output:
// 0
// 1
// 2
// 3
// 4
```

![](https://corehome.oss-accelerate.aliyuncs.com/blogs/10b9e1d3-cfa2-4d78-86e2-25e835cd8c7f.jpg)

## 将 JSON 序列化为流

在 .NET 6 中允许你将 JSON 对象序列化为 Stream，也允许你将 Stream 反序列化为 JSON 对象。

```csharp
string json = "{\"Value\":\"Deserialized from stream\"}";
byte[] bytes = Encoding.UTF8.GetBytes(json);

// Deserialize from stream
using MemoryStream ms = new MemoryStream(bytes);
Example desializedExample = JsonSerializer.Deserialize<Example>(ms);
Console.WriteLine(desializedExample.Value);
// Output: Deserialized from stream

// ==================================================================

// Serialize to stream
JsonSerializerOptions options = new() { WriteIndented = true };
using Stream outputStream = Console.OpenStandardOutput();
Example exampleToSerialize = new() { Value = "Serialized from stream" };
JsonSerializer.Serialize<Example>(outputStream, exampleToSerialize, options);
// Output:
// {
//    "Value": "Serialized from stream"
// }

class Example
{
	public string Value { get; set; }
}
```

## 像 DOM 一样使用 JSON

新类型：
- JsonArray
- JsonNode
- JsonObject
- JsonValue

```csharp
// Parse a JSON object
JsonNode jNode = JsonNode.Parse("{\"Value\":\"Text\",\"Array\":[1,5,13,17,2]}");
string value = (string)jNode["Value"];
Console.WriteLine(value); // Text
                          // or
value = jNode["Value"].GetValue<string>();
Console.WriteLine(value); // Text

int arrayItem = jNode["Array"][1].GetValue<int>();
Console.WriteLine(arrayItem); // 5
                              // or
arrayItem = jNode["Array"][1].GetValue<int>();
Console.WriteLine(arrayItem); // 5

// Create a new JsonObject
var jObject = new JsonObject
{
	["Value"] = "Text",
	["Array"] = new JsonArray(1, 5, 13, 17, 2)
};
Console.WriteLine(jObject["Value"].GetValue<string>());  // Text
Console.WriteLine(jObject["Array"][1].GetValue<int>());  // 5

// Converts the current instance to string in JSON format
string json = jObject.ToJsonString();
Console.WriteLine(json); // {"Value":"Text","Array":[1,5,13,17,2]}
```

TOP