译注
可能有的小伙伴已经知道了，在.NET Core 3.0中微软加入了对JSON的内置支持。
一直以来.NET开发者们已经习惯使用Json.NET这个强大的库来处理JSON。
那么.NET为什么要增加JSON的内置支持呢？
最近，.NET的官方博客再次发表文章说明了这么做的原因、并介绍了相关API的用法。
现翻译出来分享给大家。
原文地址: https://devblogs.microsoft.com/dotnet/try-the-new-system-text-json-apis/
尝试新的System.Text.Json API
对于.NET Core 3.0，我们 提供了一个名为System.Text.Json的全新命名空间 ，支持读取器/写入器，文档对象模型（DOM）和序列化。在这篇博文中，我告诉你为什么我们建造它，它是如何工作的，以及你如何试用它。
我们还有一个视频：
https://sec.ch9.ms/ch9/f427/704ea54a-dac0-4ef8-b1bc-e9fde129f427/onNET_high.mp4
获取新的JSON库
如果您的目标是.NET Core。安装最新版本的.NET Core 3.0预览版。这为您提供了新的JSON库和ASP.NET Core集成。
如果您的目标是.NET Standard或.NET Framework。安装System.Text.JsonNuGet包（确保包含预览并安装版本4.6.0-preview6.19303.8或更高版本）。为了与ASP.NET Core集成，您必须以.NET Core 3.0为目标。
.NET Core 3.0中JSON的未来
JSON已经成为几乎所有现代.NET应用程序的重要组成部分，并且在许多情况下甚至超过了XML的使用范围。但是，.NET还没有（强大的）内置方式来处理JSON。相反，我们一直依赖Json.NET，它继续为.NET生态系统提供良好的服务。
我们已经决定构建一个新的JSON库：
提供高性能的JSON API。我们需要一组新的JSON API，这些API通过使用Span<T> 可以高度优化性能， 并且可以直接处理UTF-8而无需转码为UTF-16 string 实例。这两个方面对于ASP.NET Core至关重要，因为吞吐量是关键要求。我们考虑过对Json.NET做出贡献，但如果不破坏现有的Json.NET客户或者破坏我们可以实现的性能，这被认为是不可能的。有了这些 System.Text.Json，我们可以获得1.3倍速--5倍的速度，具体取决于场景（更多细节见下文）。我们相信我们仍然可以挤出更多。
从ASP.NET Core中删除Json.NET依赖项。今天，ASP.NET Core依赖于Json.NET。虽然这提供了ASP.NET Core和Json.NET之间的紧密集成，但它也意味着Json.NET的版本由底层平台决定。但是，Json.NET经常更新，应用程序开发人员通常希望 - 甚至必须 - 使用特定版本。因此，我们希望从ASP.NET Core 3.0中删除Json.NET依赖项，以便客户可以选择使用哪个版本，而不必担心它们可能会意外破坏底层平台。
为Json.NET提供ASP.NET Core集成包。Json.NET基本上已成为.NET中JSON处理的瑞士军刀。它提供了许多选项和工具，使客户可以轻松地处理其JSON需求。我们不想在客户今天获得的Json.NET支持上妥协。例如，能够通过AddJsonOptions 扩展方法在ASP.NET Core中配置JSON序列化 。因此，我们希望为ASP.NET Core提供Json.NET集成作为开发人员可以选择安装的NuGet包，这样他们就可以获得今天从Json.NET获得的所有功能。此工作项的另一部分是确保我们拥有正确的扩展点，以便其他方可以为其选择的JSON库提供类似的集成包。
有关动机及其与Json.NET的关系的更多详细信息，请查看 我们在10月份发布的公告。
直接使用System.Text.Json
对于所有示例，请确保导入以下两个名称空间：
using System.Text.Json;
using System.Text.Json.Serialization;
使用序列化器
该 System.Text.Json 序列化器可以异步读写JSON并且对UTF-8文本进行了优化，使其成为理想的REST API和后端应用程序。
class WeatherForecast
{
public DateTimeOffset Date { get; set; }
public int TemperatureC { get; set; }
public string Summary { get; set; }
}
string Serialize(WeatherForecast value)
{
return JsonSerializer.ToString<WeatherForecast>(value);
}
默认情况下，我们生成缩小的JSON。如果要生成易读的内容，可以将 JsonSerializerOptions 的实例传递给序列化程序。这也是您配置其他设置的方式，例如处理注释，尾随逗号和命名策略。
string SerializePrettyPrint(WeatherForecast value)
{
var options = new JsonSerializerOptions
{
WriteIndented = true
};
return JsonSerializer.ToString<WeatherForecast>(value, options);
}
反序列化的工作方式类似：
// {
// "Date": "2013-01-20T00:00:00Z",
// "TemperatureC": 42,
// "Summary": "Typical summer in Seattle. Not.",
// }
WeatherForecast Deserialize(string json)
{
var options = new JsonSerializerOptions
{
AllowTrailingCommas = true
};
return JsonSerializer.Parse<WeatherForecast>(json, options);
}
我们还支持异步序列化和反序列化：
async Task SerializeAsync(WeatherForecast value, Stream stream)
{
await JsonSerializer.WriteAsync<WeatherForecast>(value, stream);
}
您还可以使用自定义属性来控制序列化行为，例如，忽略属性并在JSON中指定属性的名称：
class WeatherForecast
{
public DateTimeOffset Date { get; set; }
// 总是使用摄氏度
[JsonPropertyName("temp")]
public int TemperatureC { get; set; }
public string Summary { get; set; }
// 不序列化这个属性
[JsonIgnore]
public bool IsHot => TemperatureC >= 30;
}
我们目前不支持F#特定行为（例如有区别的联合和记录类型），但我们 计划将来添加它。
使用DOM
有时您不希望反序列化JSON有效负载，但您仍希望对其内容进行结构化访问。例如，假设我们有一组温度，并希望计算出星期一的平均温度：
[
{
"date": "2013-01-07T00:00:00Z",
"temp": 23,
},
{
"date": "2013-01-08T00:00:00Z",
"temp": 28,
},
{
"date": "2013-01-14T00:00:00Z",
"temp": 8,
},
]
使用 JsonDocument 类可以很容易地访问各个属性和值。
double ComputeAverageTemperatures(string json)
{
var options = new JsonReaderOptions
{
AllowTrailingCommas = true
};
using (JsonDocument document = JsonDocument.Parse(json, options))
{
int sumOfAllTemperatures = 0;
int count = 0;
foreach (JsonElement element in document.RootElement.EnumerateArray())
{
DateTimeOffset date = element.GetProperty("date").GetDateTimeOffset();
if (date.DayOfWeek == DayOfWeek.Monday)
{
int temp = element.GetProperty("temp").GetInt32();
sumOfAllTemperatures += temp;
count++;
}
}
var averageTemp = (double)sumOfAllTemperatures / count;
return averageTemp;
}
}
使用写入器(Writer)
写入器很容易使用:
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();
}
string json = Encoding.UTF8.GetString(stream.ToArray());
Console.WriteLine(json);
}
读取器需要在不同的token类型间切换处理:
byte[] data = Encoding.UTF8.GetBytes(json);
Utf8JsonReader reader = new Utf8JsonReader(data, isFinalBlock: true, state: default);
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 value = reader.GetInt32();
Console.Write(" ");
Console.Write(value);
break;
}
// Other token types elided for brevity
}
Console.WriteLine();
}
与ASP.NET Core集成
在接受或返回对象有效负载时，通过自动序列化提供ASP.NET内核中大多数JSON的使用，这反过来意味着大多数应用程序的代码与ASP.NET Core正在使用的JSON库无关。这使得从一个切换到另一个变得容易。
您可以在本文后面看到有关如何在MVC和SignalR中启用新JSON库的详细信息。
与ASP.NET Core MVC集成
在预览版5中，ASP.NET Core MVC增加了对使用JSON读写的支持 System.Text.Json。从Preview 6开始，默认情况下使用新的JSON库来序列化和反序列化JSON有效负载。
可以使用MvcOptions配置序列化程序的选项 ：
services.AddControllers()
.AddJsonOptions(options => options.JsonSerializerOptions.WriteIndented = true);
如果您想切换回之前的默认使用方式Newtonsoft.Json，请执行以下操作：
安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet包。
在 ConfigureServices() 中加入 AddNewtonsoftJson()的调用
public void ConfigureServices(IServiceCollection services)
{
...
services.AddControllers()
+ .AddNewtonsoftJson()
...
}
已知的问题
System.Text.Json 对OpenAPI / Swagger的支持正在进行，并且不太可能作为3.0版本的一部分提供。
与SignalR集成
System.Text.Json 现在是SignalR客户端和服务器在ASP.NET Core 3.0 Preview 5中使用的默认集线协议(Hub Protocol)。
如果您想切换回以前的默认使用 Newtonsoft.Json，那么您可以在客户端和服务器上执行此操作。
安装 Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson NuGet包。
在客户端 HubConnectionBuilder 中添加 .AddNewtonsoftJsonProtocol() ：
new HubConnectionBuilder()
.WithUrl("/chatHub")
.AddNewtonsoftJsonProtocol()
.Build();
在服务器AddSignalR()调用中添加 .AddNewtonsoftJsonProtocol()：
services.AddSignalR()
.AddNewtonsoftJsonProtocol();
性能
由于此功能受性能的强烈推动，我们希望分享新API的一些高级性能特征。
请记住，这些都是基于预览版本，最终数字很可能会有所不同。我们还在调整会影响性能的默认行为（例如，区分大小写）。请注意，这些都是微基准测试。您的里程肯定会有所不同，因此如果性能对您至关重要，请确保针对最能代表您工作负载的方案进行自己的测量。如果您遇到希望我们进一步优化的方案，请提交错误。
原生 System.Text.Json
只需进行微基准测试即可 System.Text.Json 与Json.NET 进行比较 ，得出以下结果：
| 场景 | 速度 | 内存 |
|---|---|---|
| 反序列化 | 快2倍 | 持平或更低 |
| 序列化 | 快1.5倍 | 持平或更低 |
| 文件（只读） | 快3-5倍 | <1 MB无分配 |
| 读取器 | 快2-3倍 | 无分配（直到实现值(materialize values)） |
| 写入器 | 快1.3-1.6倍 | 无分配 |
ASP.NET Core MVC 中的 System.Text.Json
我们编写了一个ASP.NET Core应用程序，可以动态生成 数据 ，然后从MVC控制器进行序列化和反序列化 。然后我们改变有效载荷大小并测量结果：
JSON反序列化（输入）
| 描述 | 吞吐量(RPS) | CPU (%) | 内存 (MB) |
|---|---|---|---|
| Newtonsoft.Json – 500 B | 136,435 | 95 | 172 |
| System.Text.Json – 500 B | 167,861 | 94 | 169 |
| Newtonsoft.Json – 2.4 KB | 97,137 | 97 | 174 |
| System.Text.Json – 2.4 KB | 32,026 | 96 | 169 |
| Newtonsoft.Json – 40 KB | 7,712 | 88 | 212 |
| System.Text.Json – 40 KB | 16,625 | 96 | 193 |
JSON序列化（输出）
| 描述 | 吞吐量(RPS) | CPU(%) | 内存（MB） |
|---|---|---|---|
| Newtonsoft.Json - 500 B | 120,273 | 94 | 174 |
| System.Text.Json - 500 B | 145,631 | 94 | 173 |
| Newtonsoft.Json - 8 KB | 35,408 | 98 | 187 |
| System.Text.Json - 8 KB | 56,424 | 97 | 184 |
| Newtonsoft.Json - 40 KB | 8,416 | 99 | 202 |
| System.Text.Json - 40 KB | 14,848 | 98 | 197 |
对于最常见的有效负载大小， System.Text.Json 在输入和输出格式化期间，MVC的吞吐量增加约20％，内存占用量更小。
摘要
在.NET Core 3.0中，我们将发布新的 System.Text.Json API，它们提供对JSON的内置支持，包括读取器/写入器，只读DOM和序列化/反序列化。主要目标是性能，我们看到的一般速度比Json.NET高出2倍，但这取决于您的场景和有效负载，因此请确保衡量对您来说重要的因素。
ASP.NET Core 3.0包含支持 System.Text.Json，默认情况下已启用。
试试 System.Text.Json 吧，然后反馈给我们！
{"happy": "coding!"}
