详解.NET Core 3.0 里新的JSON API

为什么需要新的 JSON API ？

JSON.NET  大家都用过，老版本的 ASP.NET Core 也依赖于 JSON.NET 。  

然而这个依赖就会引起一些版本问题：例如 ASP .NET  Core某个版本需要使用 JSON .NET  v10 ，而另一个库需要使用 JSON.NET  v11 ；或者 JSON .NET   出现了一个新版本，而ASP .NET Core 还不能支持这个版本，而您却想使用该版本。  

System.Text.Json  

随着 NET Core  3.0 的出现，出现了 System .Text.Json 命名空间和它下面一些用于处理 JSON 的类。  

特点

这个内置 JSON API 具有与生俱来的高性能、地分配的特点：  

JSON .NET  使用 .NET  里面的字符串作为基本数据类型，其实也就是 UTF16 ，而 .NET Core 中新的 JSON  API 直接使用数据原始的 UTF8 格式。  

新的 JSON API 基于 Span <byte> 这个数据类型来进行操作 JSON 数据，从而具有低分配的特点，这就可以极大的改善吞吐量和内存使用情况。  

但是新的JSON API 的特性还不那么丰富，有一些 JSON .NET 具有的特性都还不支持。  

例子  

随便找了一个 JSON 示例文件：  

针对这个文件，需要修改一下它的属性：

Utf8JsonReader  

先使用   Utf8JsonReader  来读取JSON文件。  

Utf8JsonReader   并不会读取文件或者 stream ，它会读取Span数据类型。  

直接上代码：

Main方法里面，我们使用 File .ReadAllBytes 从 sample .json 文件读取数格式为 byte[] ，然后通过 AsSpan 这个扩展方法将其转化为 Span <byte> 数据类型，然后把它传递到   Utf8JsonReader  的构造函数来创建一个JSON的 reader 。  

接下来使用while循环对JSON数据的每个 Token 进行读取，每次执行 Read() 方法时， reader 就会移动到 JSON 数据里面的下一个 Token 那里。  

Token 分成几种类型， GetToken Info 方法就是判断一下 Token 的类型，并返回一些描述性信息，这里面应该是包含了所有的类型。这里面使用到了C#  8  的  switch  表达式。  

运行程序

结果如下：

可以看到 sample.json 文件里面的每个 Token 都被正确的显示了。  

Json Document 类  

Json Document 是基于 Utf8JsonReader  构建的 。 JsonDocument  可分析  JSON  数据并生成只读文档对象模型  (DOM) ，可对模型进行查询，以支持随机访问和枚举。使用  JsonDocument  分析常规  JSON  有效负载并访问其所有成员比使用  Json.NET  快  2-3  倍，且为合理大小（即  < 1 MB ）的数据所分配的量非常少。  

JsonDocument 可以处理 Span ，也可以处理 Stream 。  

例子：

这里我通过 File .OpenRead 把 json 文件转化为 stream 。然后使用 Json Document.Parse 方法把 stream 解析成 JSON 文档对象模型。  

注意，这里我使用了 C# 8 的 using var 语法，这个以后再说。  

下面我们开始从这个 JSON 文档对象模型的根节点开始遍历，也就是 RootElement ：  

然后通过 root 这个 JsonElement 类型的对象的 GetProperty 方法来获得相应的属性，而且这个方法可以连串使用：  

最后一行使用 GetString 方法来获得该属性的字符串值。  

然后我们可以写一个递归调用的方法来遍历整个模型的每个属性：

这个方法接受 JsonElement 类型的对象，然后对该元素的属性进行循环。  

如果当前属性是另一个对象，那么就继续递归调用这个方法；

否则就输出原始的文本。

最后调用该方法：

输出结果为：

与json文件的内容匹配。

Utf8JsonWriter 类  

下面研究一下如何写入json文件。这里需要使用Utf 8JsonWriter 类。  

直接看代码：

这个类需要传递的参数类型是 Stream 或者Buffer，也就是向 Stream 或 Buffer 里面写入数据。  

那么就提供一个 buffer ：  

下面单独写一个方法，来生成json数据：

参数类型是Utf 8JsonWriter 。通过智能提示可以看到它提供了很多用于写入不同类型数据的方法。  

写 JSON 对象  

现在我想写一个json对象，那么就从Write StartObject () 开始，然后以WriteEnd Object() 结束 :  

这样的话，实际上我已经拥有了一个合法的json文档。

写属性和值  

可以分开写属性和值：

也可以同时把属性和值写出来：

显示 JSON 数据  

我先写这些内容，然后在Main方法里面调用一下：

首先需要告诉writer把它的内容flush给buffer，使用这个buffer我们可以获得 writer 的输出，这样的话就会得到一个byte数组，然后把这个 byte 数组转化为字符串，这样就可以在控制台显示它了：  

运行一下看看效果：

没啥太大的问题，就是格式不好看。

对输出进行格式化  

.NET Core 提供了一个 JsonWrite r Options 类，它可以对Writer进行一些设置。  

这里对输出进行了缩进，最后把这个options传递给Utf 8JsonWriter 的构造函数即可。  

再次运行：

现在好看多了。

JsonSerializer  

前面几节的内容可能稍微有点底层，我们大部分时候可能只需要对 C# 的类进行串行化或者将 JSON 数据反串行化成 C# 类，在 .NET Core  3.0 里面，我们可以使用 JsonSerializer 这个类来做这些事情。  

例子:

还是使用之前用到的 json 数据：  

然后我们需要建建立两个类，对应这个文件：

反串行化  

可以使用Json Serializer 类的 Deserialize() 方法对 json 数据反串行化。这个方法支持三种类型的输入参数，分别是：  

• JSON数据的字符串
• Utf 8JsonReader  
• Read OnlySpan<byte> ，它里面包含 JSON 数据  

为了简单一点，我直接把json文件读取成字符串，然后传给 Deserialize 方法：  

然后我试图打印出反串行化之后的一些属性数据。但是这不会成功。因为JSON文件里面数据的大小写命名规范使用的是 camel casing （简单理解为首字母是小写的），而默认情况下 Deserializer 会寻找 Pascal casing 这种规范（简单理解为每个单词的首字母都是大写的）的属性名。  

格式化  

为解决这个问题，就需要使用 JsonSerializerOptions 类：  

建立该类的一个实例，设置 Property NamingPolicy 为 CamelCase ，然后把这个实例传递给 Deserialize 方法的第二个参数。  

运行看结果 :  

这次就没有问题了。

串行化  

Json Serializer 也支持串行化，也就是把C#数据转化为 JSON 数据：  

这里使用了相同的 options 。  

运行结果：

如果想让输出结果更好看一些，可以在 JsonSerializerOptions 里面进行相应的设置：  

这次输出结果为：

总结  

总结一下 .NET Core 3.0 新的JSON  API ：  

• Utf 8JsonReader -  读操作，快速，低级  
• Utf 8JsonWriter -  写操作，快速，低级  
• JsonDocument -  基于DOM，快速  
• Json Seriliazer -  串行化 / 反串行化，快速  

另外 JSON .NET  仍然被支持。