JSON-serialisatie en deserialisatie (marshalling en unmarshalling) in .NET - overzicht
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:
- Kenmerken uit de System.Runtime.Serialization naamruimte.
- Het System.SerializableAttribute kenmerk en de ISerializable interface. Deze typen worden alleen gebruikt voor binaire en XML-serialisatie.
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.Json httpContent.
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.
