[譯]試用新的System.Text.Json API

本文轉載自查看原文 2019-06-15 15:12 6523 C#/ .net/ JSON/ JSON.NET/ .NET CORE

譯注

可能有的小伙伴已經知道了，在.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!"}

免責聲明！

本站轉載的文章為個人學習借鑒使用，本站對版權不負任何法律責任。如果侵犯了您的隱私權益，請聯系本站郵箱yoyou2525@163.com刪除。

猜您在找 試用新的System.Text.Json API 【譯】System.Text.Json 的下一步是什么在.Net Core 3.0中嘗試新的System.Text.Json API System.Text.Json的JsonDocument類講解 System.Text.Json 常規用法使用System.Text.Json處理Json文檔以及部分坑 .NET 5的System.Text.Json的JsonDocument類講解 C# 通過Dynamic訪問System.Text.Json對象 .NET Core 內置的 System.Text.Json 使用注意 c# System.Text.Json 精講