Serialisasi dan deserialisasi JSON (marshalling dan unmarshalling) di .NET - gambaran umum

  • Artikel

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

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:

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.

Sumber Daya Tambahan: