Serializacja i deserializacja JSON (marshalling i unmarshalling) na platformie .NET — omówienie

  • Artykuł

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:

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.

Emocje ion 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 Emocje ion a 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.

Dodatkowe zasoby