Serialisasi dan deserialisasi JSON (marshalling dan unmarshalling) di .NET - gambaran umum
Namespace System.Text.Json menyediakan fungsionalitas untuk membuat serialisasi ke dan deserialisasi dari JavaScript Object Notation (JSON). Serialisasi adalah proses mengonversi status objek, yaitu, nilai propertinya, menjadi bentuk yang dapat disimpan atau ditransmisikan. Formulir berseri tidak menyertakan informasi apa pun tentang metode terkait objek. Deserialisasi merekonstruksi objek dari formulir yang diserialisasikan.
Desain System.Text.Json pustaka menekankan performa tinggi dan alokasi memori rendah melalui set fitur yang luas. Dukungan UTF-8 bawaan mengoptimalkan proses membaca dan menulis teks JSON yang dikodekan sebagai UTF-8, yang merupakan pengodean paling umum untuk data di web dan file di disk.
Pustaka juga menyediakan kelas untuk bekerja dengan model objek dokumen (DOM) di dalam memori. Fitur ini memungkinkan akses acak ke elemen dalam file atau string JSON.
Untuk Visual Basic, ada beberapa batasan pada bagian pustaka apa yang dapat Anda gunakan. Untuk informasi selengkapnya, lihat dukungan (Visual Basic).
Cara mendapatkan pustaka
Pustaka bawaan sebagai bagian dari kerangka kerja bersama untuk .NET Core 3.0 dan versi yang lebih baru. Fitur pembuatan sumber adalah bawaan sebagai bagian dari kerangka kerja bersama untuk .NET 6 dan versi yang lebih baru.
Untuk versi kerangka kerja yang lebih lama dari .NET Core 3.0, instal paket NuGet System.Text.Json. Paket ini mendukung:
- .NET Standard 2.0 dan yang lebih baru
- .NET Framework 4.6.2 dan yang lebih baru
- Versi .NET Core 2.1 dan yang lebih baru.
- .NET 5 dan yang lebih baru
Namespace dan API
- Namespace System.Text.Json berisi semua titik masuk dan jenis utama.
- Namespace System.Text.Json.Serialization berisi atribut dan API untuk skenario tingkat lanjut dan penyesuaian khusus untuk serialisasi dan deserialisasi.
Contoh kode yang ditunjukkan dalam artikel ini memerlukan using arahan untuk satu atau kedua namespace ini.
Penting
System.Text.Json tidak mendukung API serialisasi berikut yang mungkin telah Anda gunakan sebelumnya:
- Atribut dari System.Runtime.Serialization namespace layanan.
- Atribut System.SerializableAttribute dan ISerializable antarmuka. Jenis ini hanya digunakan untuk serialisasi Biner dan XML.
Metode ekstensi HttpClient dan HttpContent
Membuat serial dan membatalkan pembuatan serial payload JSON dari jaringan adalah operasi yang umum. Metode ekstensi pada HttpClient dan HttpContent memungkinkan Anda melakukan operasi ini dalam satu baris kode. Metode ekstensi ini menggunakan default web untuk JsonSerializerOptions.
Contoh berikut mengilustrasikan penggunaan HttpClientJsonExtensions.GetFromJsonAsync dan 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
Ada juga metode ekstensi untuk System.Text.Json di HttpContent.
Refleksi vs. pembuatan sumber
Secara default, System.Text.Json mengumpulkan metadata yang diperlukan untuk mengakses properti objek untuk serialisasi dan deserialisasi pada waktu proses menggunakan refleksi. Sebagai alternatif, System.Text.Json dapat menggunakan fitur pembuatan sumber C# untuk meningkatkan performa, mengurangi penggunaan memori privat, dan memfasilitasi pemangkasan rakitan, yang mengurangi ukuran aplikasi.
Untuk informasi selengkapnya, lihat Refleksi versus pembuatan sumber.
Informasi keamanan
Untuk informasi tentang ancaman keamanan yang dipertimbangkan saat merancang JsonSerializer, dan bagaimana ancaman tersebut dapat dimitigasi, lihat System.Text.Json Model Ancaman.
Keamanan utas
Serializer System.Text.Json dirancang dengan mengingat keamanan utas. Praktis, ini berarti bahwa setelah dikunci, JsonSerializerOptions instans dapat dibagikan dengan aman di beberapa utas. JsonDocument menyediakan representasi DOM yang tidak dapat diubah, dan dalam .NET 8 dan versi yang lebih baru, aman utas, representasi DOM untuk nilai JSON.
