.NET의 JSON 직렬화 및 역직렬화(마샬링 및 역 마샬링) - 개요

  • 아티클

System.Text.Json 네임스페이스는 JSON(JavaScript Object Notation)에서 직렬화 및 역직렬화하는 기능을 제공합니다. Serialization은 개체의 상태, 즉 속성 값을 저장하거나 전송할 수 있는 형식으로 변환하는 프로세스입니다. 직렬화된 양식에는 개체의 연결된 메서드에 대한 정보가 포함되지 않습니다. Deserialization은 직렬화된 형식에서 개체를 다시 생성합니다.

System.Text.Json 라이브러리 디자인은 광범위한 기능 집합에 비해 높은 성능과 낮은 메모리 할당을 강조합니다. 기본 제공 UTF-8 지원은 UTF-8로 인코딩된 JSON 텍스트를 읽고 쓰는 프로세스를 최적화합니다. 이는 웹의 데이터와 디스크의 파일에 가장 널리 사용되는 인코딩입니다.

라이브러리는 메모리 내 DOM(문서 개체 모델)을 사용하기 위한 클래스도 제공합니다. 이 기능을 사용하면 JSON 파일 또는 문자열의 요소에 대한 임의 액세스가 가능합니다.

Visual Basic의 경우 사용할 수 있는 라이브러리 부분에는 몇 가지 제한 사항이 있습니다. 자세한 내용은 Visual Studio 지원을 참조하세요.

라이브러리를 가져오는 방법

라이브러리는 .NET Core 3.0 이상 버전에서 공유 프레임워크의 일부로 기본 제공됩니다. 원본 생성 기능은 .NET 6 이상 버전에서 공유 프레임워크의 일부로 기본 제공됩니다.

.NET Core 3.0 이전 프레임워크 버전의 경우 System.Text.Json NuGet 패키지를 설치합니다. 패키지는 다음을 지원합니다.

  • .NET Standard 2.0 이상
  • .NET Framework 4.6.2 이상
  • .NET Core 2.1 이상
  • .NET 5 이상

네임스페이스 및 API

  • System.Text.Json 네임스페이스에는 모든 진입점과 기본 형식이 포함되어 있습니다.
  • System.Text.Json.Serialization 네임스페이스에는 직렬화 및 역직렬화와 관련된 고급 시나리오 및 사용자 지정을 위한 특성과 API가 포함되어 있습니다.

이 문서에 표시된 코드 예제에는 이러한 네임스페이스 중 하나 또는 둘 다에 대해 using 지시문이 필요합니다.

Important

System.Text.Json에서는 이전에 사용했을 수도 있는 다음 serialization API를 지원하지 않습니다.

HttpClient 및 Httpclient 확장 메서드

네트워크에서 JSON 페이로드를 직렬화 및 역직렬화하는 작업은 일반적인 작업입니다. HttpClient 및 Httpclient 확장 메서드를 사용하면 코드 한 줄로 이러한 작업을 수행할 수 있습니다. 이러한 확장 메서드는 JsonSerializerOptions의 웹 기본값을 사용합니다.

다음 예제는 HttpClientJsonExtensions.GetFromJsonAsync 및 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

HttpContent에는 System.Text.Json의 확장 메서드도 있습니다.

리플렉션과 소스 생성

기본적으로 System.Text.Json은 리플렉션을 사용하여 런타임에 serialization 및 deserialization를 위해 객체의 속성에 액세스하는 데 필요한 메타데이터를 수집합니다. 또는 System.Text.Json은 C# 원본 생성 기능을 사용하여 성능을 개선하고, 프라이빗 메모리 사용량을 줄이며, 어셈블리 트리밍을 용이하게 하여 앱 크기를 줄일 수 있습니다.

자세한 내용은 리플렉션 및 원본 생성을 참조하세요.

보안 정보

JsonSerializer를 디자인할 때 고려된 보안 위협 및 완화 방법에 대한 내용은 System.Text.Json 위협 모델을 참조하세요.

스레드로부터의 안전성

System.Text.Json 직렬 변환기는 스레드 안전을 염두에 두고 설계되었습니다. 실제로 일단 잠그기만 하면 JsonSerializerOptions 인스턴스를 여러 스레드에서 안전하게 공유할 수 있습니다. JsonDocument는 JSON 값에 대해 변경 불가능하며 .NET 8 이상 버전에서는 스레드로부터 안전한 DOM 표현을 제공합니다.

추가 자료