Serializacja i deserializacja JSON (marshalling i unmarshalling) na platformie .NET — omówienie
System.Text.Json Przestrzeń nazw zapewnia funkcje serializacji do i deserializacji z pliku JavaScript Object Notation (JSON). Serializacja to proces konwertowania stanu obiektu, czyli wartości jego właściwości na formularz, który można przechowywać lub przesyłać. Formularz serializowany nie zawiera żadnych informacji o metodach skojarzonych z obiektem. Deserializacja rekonstrukuje obiekt z postaci serializowanej.
Projekt System.Text.Json biblioteki podkreśla wysoką wydajność i niską alokację pamięci w ramach rozbudowanego zestawu funkcji. Wbudowana obsługa protokołu UTF-8 optymalizuje proces odczytywania i zapisywania tekstu JSON zakodowanego jako UTF-8, który jest najbardziej rozpowszechnionym kodowaniem danych w internecie i plikach na dysku.
Biblioteka udostępnia również klasy do pracy z modelem obiektów dokumentów w pamięci (DOM). Ta funkcja umożliwia losowy dostęp do elementów w pliku lub ciągu JSON.
W przypadku języka Visual Basic istnieją pewne ograniczenia dotyczące części biblioteki, których można użyć. Aby uzyskać więcej informacji, zobacz Obsługa języka Visual Basic.
Jak pobrać bibliotekę
Biblioteka jest wbudowana w ramach struktury udostępnionej dla platformy .NET Core 3.0 i nowszych wersji. Funkcja generowania źródła jest wbudowana w ramach platformy udostępnionej dla platformy .NET 6 i nowszych wersji.
W przypadku wersji platformy starszej niż .NET Core 3.0 zainstaluj System.Text.Json pakiet NuGet. Pakiet obsługuje:
- .NET Standard 2.0 lub nowszy
- .NET Framework 4.6.2 i nowsze
- .NET Core 2.1 lub nowszy
- .NET 5 lub nowszy
Przestrzenie nazw i interfejsy API
- System.Text.Json Przestrzeń nazw zawiera wszystkie punkty wejścia i główne typy.
- System.Text.Json.Serialization Przestrzeń nazw zawiera atrybuty i interfejsy API dla zaawansowanych scenariuszy i dostosowania specyficzne dla serializacji i deserializacji.
Przykłady kodu pokazane w tym artykule wymagają using dyrektyw dla jednej lub obu tych przestrzeni nazw.
Ważne
System.Text.Json program nie obsługuje następujących interfejsów API serializacji, które mogły być wcześniej używane:
- Atrybuty z System.Runtime.Serialization przestrzeni nazw.
- Atrybut System.SerializableAttribute i ISerializable interfejs. Te typy są używane tylko w przypadku serializacji binarnej i XML.
Metody rozszerzenia HttpClient i HttpContent
Serializowanie i deserializacji ładunków JSON z sieci to typowe operacje. Metody rozszerzeń w obiektach HttpClient i HttpContent umożliwiają wykonywanie tych operacji w jednym wierszu kodu. Te metody rozszerzeń używają wartości domyślnych sieci Web dla JsonSerializerOptions.
W poniższym przykładzie pokazano użycie elementów HttpClientJsonExtensions.GetFromJsonAsync i 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
Istnieją również metody rozszerzeń dla System.Text.Json protokołu HttpContent.
Odbicie a generowanie źródła
Domyślnie zbiera metadane, System.Text.Json których potrzebuje, aby uzyskać dostęp do właściwości obiektów na potrzeby serializacji i deserializacji w czasie wykonywania przy użyciu odbicia. Alternatywnie można użyć funkcji generowania źródła języka C#, System.Text.Json aby zwiększyć wydajność, zmniejszyć użycie pamięci prywatnej i ułatwić przycinanie zestawów, co zmniejsza rozmiar aplikacji.
Aby uzyskać więcej informacji, zobacz Odbicie i generowanie źródła.
Informacje o zabezpieczeniach
Aby uzyskać informacje na temat zagrożeń bezpieczeństwa, które zostały uwzględnione podczas projektowania JsonSerializeri sposobu ich ograniczenia, zobacz System.Text.Json Model zagrożeń.
Bezpieczeństwo wątkowe
System.Text.Json Serializator został zaprojektowany z myślą o bezpieczeństwie wątków. Praktycznie oznacza to, że po zablokowaniu JsonSerializerOptions wystąpienia mogą być bezpiecznie współużytkowane przez wiele wątków. JsonDocument udostępnia niezmienną reprezentację modelu DOM dla wartości JSON w wersjach .NET 8 i nowszych.
