JSON-serialisering och deserialisering (marshalling och unmarshalling) i .NET – översikt

  • Artikel

Namnområdet System.Text.Json innehåller funktioner för serialisering till och deserialisering från JavaScript Object Notation (JSON). Serialisering är processen att konvertera tillståndet för ett objekt, det vill säga värdena för dess egenskaper, till ett formulär som kan lagras eller överföras. Det serialiserade formuläret innehåller ingen information om ett objekts associerade metoder. Deserialisering rekonstruerar ett objekt från det serialiserade formuläret.

Biblioteksdesignen System.Text.Json betonar hög prestanda och låg minnesallokering över en omfattande funktionsuppsättning. Inbyggt STÖD för UTF-8 optimerar processen för att läsa och skriva JSON-text kodad som UTF-8, vilket är den vanligaste kodningen för data på webben och filer på disk.

Biblioteket innehåller också klasser för att arbeta med en minnesintern dokumentobjektmodell (DOM). Den här funktionen ger slumpmässig åtkomst till elementen i en JSON-fil eller sträng.

För Visual Basic finns det vissa begränsningar för vilka delar av biblioteket du kan använda. Mer information finns i Visual Basic-stöd.

Hämta biblioteket

Biblioteket är inbyggt som en del av det delade ramverket för .NET Core 3.0 och senare versioner. Källgenereringsfunktionen är inbyggd som en del av det delade ramverket för .NET 6 och senare versioner.

För tidigare ramverksversioner än .NET Core 3.0 installerar du System.Text.Json NuGet-paketet. Paketet stöder:

  • .NET Standard 2.0 och senare
  • .NET Framework 4.6.2 och senare
  • .NET Core 2.1 och senare
  • .NET 5 och senare

Namnområden och API:er

  • Namnområdet System.Text.Json innehåller alla startpunkter och huvudtyper.
  • Namnområdet System.Text.Json.Serialization innehåller attribut och API:er för avancerade scenarier och anpassning som är specifika för serialisering och deserialisering.

Kodexemplen som visas i den här artikeln kräver using direktiv för ett eller båda av dessa namnområden.

Viktigt!

System.Text.Json stöder inte följande serialiserings-API:er som du kanske har använt tidigare:

HttpClient- och HttpContent-tilläggsmetoder

Serialisering och deserialisering av JSON-nyttolaster från nätverket är vanliga åtgärder. Med tilläggsmetoder på HttpClient och HttpContent kan du utföra dessa åtgärder på en enda kodrad. Dessa tilläggsmetoder använder webbstandarder för JsonSerializerOptions.

I följande exempel visas användning av HttpClientJsonExtensions.GetFromJsonAsync och 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

Det finns även tilläggsmetoder för System.Text.Json på HttpContent.

Reflektion jämfört med källgenerering

Som standard System.Text.Json samlar in de metadata som behövs för att få åtkomst till egenskaper för objekt för serialisering och deserialisering vid körning med reflektion. Du kan också System.Text.Json använda C# -källgenereringsfunktionen för att förbättra prestanda, minska användningen av privat minne och underlätta monteringstrimning, vilket minskar appens storlek.

Mer information finns i Reflektion kontra källgenerering.

Säkerhetsinformation

Information om säkerhetshot som övervägdes när du designade JsonSerializeroch hur de kan åtgärdas finns i System.Text.Json Hotmodell.

Trådsäkerhet

Serialiseraren System.Text.Json utformades med trådsäkerhet i åtanke. Praktiskt taget innebär detta att instanser kan delas på ett säkert sätt mellan flera trådar när de är låsta JsonSerializerOptions . JsonDocument ger en oföränderlig, och i .NET 8 och senare versioner, trådsäker, DOM-representation för JSON-värden.

Ytterligare resurser