[译]试用新的System.Text.Json API

译注

可能有的小伙伴已经知道了,在.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,请执行以下操作:

  1. 安装 Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet包。

  2. ConfigureServices() 中加入 AddNewtonsoftJson()的调用

    public void ConfigureServices(IServiceCollection services)
    {
        ...
        services.AddControllers()
    +            .AddNewtonsoftJson()
        ...
    }
    

已知的问题

  • System.Text.JsonOpenAPI / Swagger的支持正在进行,并且不太可能作为3.0版本的一部分提供。

与SignalR集成

System.Text.Json 现在是SignalR客户端和服务器在ASP.NET Core 3.0 Preview 5中使用的默认集线协议(Hub Protocol)。

如果您想切换回以前的默认使用 Newtonsoft.Json,那么您可以在客户端和服务器上执行此操作。

  1. 安装 Microsoft.AspNetCore.SignalR.Protocols.NewtonsoftJson NuGet包。

  2. 在客户端 HubConnectionBuilder 中添加 .AddNewtonsoftJsonProtocol()

    new HubConnectionBuilder()
        .WithUrl("/chatHub")
        .AddNewtonsoftJsonProtocol()
        .Build();
    
  3. 在服务器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!"}

posted @ 2019-06-15 15:12  WAKU  阅读(6505)  评论(0编辑  收藏