在 C# 中使用 System.Text.Json

最新推荐文章于 2026-04-16 09:20:28 发布

翻译最新推荐文章于 2026-04-16 09:20:28 发布 · 1.9k 阅读

标签

#json #c# #javascript

介绍

虽然JSON是一种紧凑且易于阅读的跨语言存储和数据交换格式，但它提供的灵活性有时需要一些自定义处理来解析数据。

如果你不熟悉JSON，那么这里是来自官方http://www.json.org的定义：

引用：

JSON（JavaScript Object Notation）是一种轻量级的数据交换格式。人类很容易阅读和写作。机器很容易解析和生成。它基于 JavaScript 编程语言标准 ECMA-262 第 3 版 - 1999 年 12 月的一个子集。

微软对新System.Text.Json API 的解释：

引用：

System.Text.Json主要关注性能、安全性和标准合规性。它在默认行为上有一些关键差异，并且不旨在与NewtonSoft.Json具有相同的功能。对于某些场景，System.Text.Json目前没有内置功能，但有推荐的变通方法。对于其他情况，变通办法是不切实际的。

在下一篇文章中，我将介绍其中一个“当前没有内置功能”功能，因为它超出了本文的范围。

内容

背景

在上一篇文章中，我们讨论了“在 C# 和 VB 中使用 Newtonsoft.Json ”。本文介绍了使用简单的 JSON 对象和集合到自定义转换器、无效的集合属性名称以及从 JSON 反序列化到类的转换。

本文将通过移植旧的NewtonSoft.Json 示例项目来探索新的 System.Text.Json API 。

本文的结构和示例项目将沿用上一篇文章的结构。如果您只对新的 API 感兴趣，并且希望将NewtonSoft.Json与System.Text.Json进行比较并查看迁移过程需要什么，则可以这样做。

VB 限制

我想在本文中包含 VB 示例代码，就像我在上一篇文章中为NewtonSoft.Json 所做的那样。但是，在撰写本文时，VB 不支持用于Utf8JsonReader和Span<t>的 6.0 版 DotNet (Core) Ref Strut 类型。

因此，对于本文，我们将只使用 C#。您可以通过为自定义转换器使用单独的 C# 库来解决此限制。我们将不会在本文中介绍这一点。但是，如果您希望这样做，您需要将转换器和模型/poco 类放在同一个类库项目中以避免循环引用。

目前，如果您使用 VB，我建议您的项目使用NewtonSoft.Json。

从NewtonSoft.Json迁移到System.Text.Json

从NewtonSoft.Json迁移到System.Text.Json时，存在许多差异。Microsoft 有涵盖差异的迁移文档。

主要区别在于：

引用：

System.Text.Json默认情况下是严格的，避免代表调用者进行任何猜测或解释，强调确定性行为。该库是为了性能和安全性而有意设计的。Newtonsoft.Json 默认是灵活的。设计上的这种根本差异是默认行为的以下许多特定差异的背后。

工具和库

像任何事情一样，您需要合适的工具来完成这项工作。以下是一些可用的工具，包括本文中使用的工具。

查看者和验证者

有时，JSON 数据是打包的并且不是很可读，或者我们需要验证原始数据：

jsonhero.io - 可视化 JSON 结构和其中的数据
jsoncrack.com - 数据的图形可视化
freeformatter.com - 对多种格式的详尽支持
codebeautify.org - 对多种格式的详尽支持
jsonformatter.org - 美化、验证和转换 JSON & XML
jsonformatter.curiousconcept.com - 根据标准RFC 4627、RFC 7159、ECMA-404格式化和验证 JSON
jsonlint.com - 验证 JSON 比较和验证 JSON
Fiddler - 用于查看 HTTP 数据流量的 Web 调试代理；查看数据提供者实际发送的内容

代码生成器

我们需要创建一个类结构来将原始 JSON 数据转换为。您可以从 JSON 文件手动创建类，这是一项非常缓慢且耗时的任务。有更快的方法来完成这项工作。这里有一对：

quicktype.io - 支持 C#、TypeScript、Go Java、Elm、Swift、简单类型和模式
JSON Utils - 支持 VB 和 C#，有很多选项

注意：目前，在撰写本文时，我找不到专门支持System.Text.Json类/属性属性的生成器。

数据转换

一旦您拥有原始 JSON 数据并创建了将数据映射到的类，下一步将是反序列化到类并从类序列化。本文将重点介绍反序列化。

以下帮助程序类是处理空结果的干净实现。

C＃

标准数据类型

让我们从简单的事情开始。以下两个示例使用 .NET 原始数据和集合类型。

简单对象类型

这是来自Etsy API的 v2 类别 JSON 对象。所有 JSON 字段都映射到 .NET 原始数据类型。

JavaScript

System.Text.Json支持通过以下方式启用不区分大小写的属性名称匹配JsonSerializerOptions：

C＃

反序列化时将选项传递给序列化程序：

C＃

现在您可以使用 POCO（普通旧类对象）：

C＃

如果您想通过属性使用手动映射，请使用JsonPropertyName属性，正式JsonProperty用于 NewtonSoft。

C＃

现在我们可以将 JSON 数据反序列化为 .NET 类[es]：

C＃

现在可以处理数据了。这是附加示例应用程序的屏幕截图 ( WinFormSimpleObject)：