JSON-serialisatie en deserialisatie (marshalling en unmarshalling) in .NET - overzicht

  • Artikel

De System.Text.Json naamruimte biedt functionaliteit voor het serialiseren naar en deserialiseren van JavaScript Object Notation (JSON). Serialisatie is het proces van het converteren van de status van een object, dat wil gezegd de waarden van de eigenschappen ervan, in een formulier dat kan worden opgeslagen of verzonden. Het geserialiseerde formulier bevat geen informatie over de bijbehorende methoden van een object. Deserialisatie reconstrueert een object uit de geserialiseerde vorm.

Het System.Text.Json bibliotheekontwerp benadrukt hoge prestaties en lage geheugentoewijzing ten opzichte van een uitgebreide functieset. Ingebouwde UTF-8-ondersteuning optimaliseert het lezen en schrijven van JSON-tekst die is gecodeerd als UTF-8. Dit is de meest voorkomende codering voor gegevens op internet en bestanden op schijf.

De bibliotheek biedt ook klassen voor het werken met een documentobjectmodel (DOM) in het geheugen. Met deze functie kunt u willekeurige toegang krijgen tot de elementen in een JSON-bestand of -tekenreeks.

Voor Visual Basic gelden enkele beperkingen voor de onderdelen van de bibliotheek die u kunt gebruiken. Zie Visual Basic-ondersteuning voor meer informatie.

De bibliotheek ophalen

De bibliotheek is ingebouwd als onderdeel van het gedeelde framework voor .NET Core 3.0 en latere versies. De functie voor het genereren van bronnen is ingebouwd als onderdeel van het gedeelde framework voor .NET 6 en latere versies.

Installeer het System.Text.Json NuGet-pakket voor frameworkversies die ouder zijn dan .NET Core 3.0. Het pakket ondersteunt:

  • .NET Standard 2.0 en hoger
  • .NET Framework 4.6.2 en hoger
  • .NET Core 2.1 en hoger
  • .NET 5 en hoger

Naamruimten en API's

  • De System.Text.Json naamruimte bevat alle toegangspunten en de hoofdtypen.
  • De System.Text.Json.Serialization naamruimte bevat kenmerken en API's voor geavanceerde scenario's en aanpassingen die specifiek zijn voor serialisatie en deserialisatie.

De codevoorbeelden in dit artikel vereisen using instructies voor een of beide naamruimten.

Belangrijk

System.Text.Json biedt geen ondersteuning voor de volgende serialisatie-API's die u mogelijk eerder hebt gebruikt:

HttpClient- en HttpContent-extensiemethoden

JSON-nettoladingen van het netwerk serialiseren en deserialiseren zijn veelvoorkomende bewerkingen. Met extensiemethoden op HttpClient en HttpContent kunt u deze bewerkingen uitvoeren in één regel code. Deze extensiemethoden maken gebruik van webstandaarden voor JsonSerializerOptions.

In het volgende voorbeeld ziet u het gebruik van HttpClientJsonExtensions.GetFromJsonAsync en HttpClientJsonExtensions.PostAsJsonAsync:

using System.Net.Http.Json;

namespace HttpClientExtensionMethods
{
    public class User
    {
        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Username { get; set; }
        public string? Email { get; set; }
    }

    public class Program
    {
        public static async Task Main()
        {
            using HttpClient client = new()
            {
                BaseAddress = new Uri("https://jsonplaceholder.typicode.com")
            };

            // Get the user information.
            User? user = await client.GetFromJsonAsync<User>("users/1");
            Console.WriteLine($"Id: {user?.Id}");
            Console.WriteLine($"Name: {user?.Name}");
            Console.WriteLine($"Username: {user?.Username}");
            Console.WriteLine($"Email: {user?.Email}");

            // Post a new user.
            HttpResponseMessage response = await client.PostAsJsonAsync("users", user);
            Console.WriteLine(
                $"{(response.IsSuccessStatusCode ? "Success" : "Error")} - {response.StatusCode}");
        }
    }
}

// Produces output like the following example but with different names:
//
//Id: 1
//Name: Tyler King
//Username: Tyler
//Email: Tyler @contoso.com
//Success - Created

Imports System.Net.Http
Imports System.Net.Http.Json

Namespace HttpClientExtensionMethods

    Public Class User
        Public Property Id As Integer
        Public Property Name As String
        Public Property Username As String
        Public Property Email As String
    End Class

    Public Class Program

        Public Shared Async Function Main() As Task
            Using client As New HttpClient With {
                .BaseAddress = New Uri("https://jsonplaceholder.typicode.com")
                }

                ' Get the user information.
                Dim user1 As User = Await client.GetFromJsonAsync(Of User)("users/1")
                Console.WriteLine($"Id: {user1.Id}")
                Console.WriteLine($"Name: {user1.Name}")
                Console.WriteLine($"Username: {user1.Username}")
                Console.WriteLine($"Email: {user1.Email}")

                ' Post a new user.
                Dim response As HttpResponseMessage = Await client.PostAsJsonAsync("users", user1)
                Console.WriteLine(
                $"{(If(response.IsSuccessStatusCode, "Success", "Error"))} - {response.StatusCode}")
            End Using
        End Function

    End Class

End Namespace

' Produces output like the following example but with different names:
'
'Id: 1
'Name: Tyler King
'Username: Tyler
'Email: Tyler @contoso.com
'Success - Created

Er zijn ook uitbreidingsmethoden voor System.Text.JsonhttpContent.

Reflectie versus brongeneratie

Verzamelt standaard System.Text.Json de metagegevens die nodig zijn voor toegang tot eigenschappen van objecten voor serialisatie en deserialisatie tijdens runtime met behulp van weerspiegeling. Als alternatief System.Text.Json kunt u de functie voor het genereren van C#-bronnen gebruiken om de prestaties te verbeteren, het gebruik van privégeheugen te verminderen en assembly's te beperken, waardoor de app kleiner wordt.

Zie Reflectie versus brongeneratie voor meer informatie.

Beveiligingsgegevens

Zie Bedreigingsmodel voor informatie over beveiligingsrisico's die werden overwogen bij het ontwerpen JsonSerializeren hoe ze kunnen worden beperktSystem.Text.Json.

Schroefdraadveiligheid

De System.Text.Json serializer is ontworpen met threadveiligheid in het achterhoofd. Praktisch betekent dit dat exemplaren veilig kunnen worden gedeeld via meerdere threads nadat ze zijn vergrendeld JsonSerializerOptions . JsonDocument biedt een onveranderbare weergave en in .NET 8 en hoger, thread-safe, DOM-weergave voor JSON-waarden.

Aanvullende bronnen