JSON-serialisering och deserialisering (marshalling och unmarshalling) i .NET – översikt
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:
- Attribut från System.Runtime.Serialization namnområdet.
- Attributet System.SerializableAttribute och ISerializable gränssnittet. Dessa typer används endast för binär- och XML-serialisering.
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.
