System.Text.Json 지원되는 형식

이 문서에서는 serialization 및 deserialization에 지원되는 형식에 대한 개요를 제공합니다.

JSON 개체로 직렬화하는 형식

다음 형식은 JSON 개체로 직렬화합니다.

• 클래스^*
• 구조체
• 인터페이스
• 레코드 및 구조체 레코드

* JSON 배열로 직렬화할 IEnumerable<T> 구현하는 사전이 아닌 형식입니다. IEnumerable<T>구현하는 사전 형식은 JSON 개체로 직렬화됩니다.

다음 코드 조각은 간단한 구조체의 serialization을 보여줍니다.

public static void Main()
{
    var coordinates = new Coords(1.0, 2.0);
    string json = JsonSerializer.Serialize(coordinates);
    Console.WriteLine(json);

    // Output:
    // {"X":1,"Y":2}
}

public readonly struct Coords
{
    public Coords(double x, double y)
    {
        X = x;
        Y = y;
    }

    public double X { get; }
    public double Y { get; }
}

JSON 배열로 직렬화하는 형식

.NET 컬렉션 형식은 JSON 배열로 직렬화됩니다. System.Text.Json.JsonSerializer 다음과 같은 경우 serialization을 위한 컬렉션 형식을 지원합니다.

• IEnumerable 또는 IAsyncEnumerable<T>파생됩니다.
• serialize할 수 있는 요소를 포함합니다.

serializer는 GetEnumerator() 메서드를 호출하고 요소를 씁니다.

역직렬화는 더 복잡하며 일부 컬렉션 형식에서는 지원되지 않습니다.

다음 섹션은 네임스페이스별로 구성되며 직렬화 및 역직렬화에 지원되는 형식을 보여 있습니다.

• System.Array 네임스페이스
• System.Collections 네임스페이스
• System.Collections.Generic 네임스페이스
• system.Collections.Immutable 네임스페이스
• System.Collections.Specialized 네임스페이스
• system.Collections.Concurrent 네임스페이스
• System.Collections.ObjectModel 네임스페이스
• 사용자 지정 컬렉션

System.Array 네임스페이스

System.Collections 네임스페이스

* 유형에 대한 지원 왕복을 참조하세요.

System.Collections.Generic 네임스페이스

* 지원되는 키 형식참조하세요.

† IAsyncEnumerable<T>다음 섹션을 참조하세요.

• 유형은 지원 왕복을 참조하세요.

IAsyncEnumerable<T>

다음 예제에서는 비동기 데이터 원본의 표현으로 스트림을 사용합니다. 원본은 로컬 컴퓨터의 파일이거나 데이터베이스 쿼리 또는 웹 서비스 API 호출의 결과일 수 있습니다.

스트림 serialization

System.Text.Json 다음 예제와 같이 IAsyncEnumerable<T> 값을 JSON 배열로 직렬화할 수 있습니다.

using System.Text.Json;

namespace IAsyncEnumerableSerialize;

public class Program
{
    public static async Task Main()
    {
        using Stream stream = Console.OpenStandardOutput();
        var data = new { Data = PrintNumbers(3) };
        await JsonSerializer.SerializeAsync(stream, data);
    }

    static async IAsyncEnumerable<int> PrintNumbers(int n)
    {
        for (int i = 0; i < n; i++)
        {
            await Task.Delay(1000);
            yield return i;
        }
    }
}
// output:
//  {"Data":[0,1,2]}

IAsyncEnumerable<T> 값은 JsonSerializer.SerializeAsync같은 비동기 serialization 메서드에서만 지원됩니다.

스트림 역직렬화

DeserializeAsyncEnumerable 메서드는 다음 예제와 같이 스트리밍 역직렬화를 지원합니다.

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserialize;

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes("[0,1,2,3,4]"));
        await foreach (int item in JsonSerializer.DeserializeAsyncEnumerable<int>(stream))
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

DeserializeAsyncEnumerable 메서드는 루트 수준 JSON 배열에서 읽기만 지원합니다.

DeserializeAsync 메서드는 IAsyncEnumerable<T>지원하지만 해당 서명은 스트리밍을 허용하지 않습니다. 다음 예제와 같이 최종 결과를 단일 값으로 반환합니다.

using System.Text;
using System.Text.Json;

namespace IAsyncEnumerableDeserializeNonStreaming;

public class MyPoco
{
    public IAsyncEnumerable<int>? Data { get; set; }
}

public class Program
{
    public static async Task Main()
    {
        using var stream = new MemoryStream(Encoding.UTF8.GetBytes(@"{""Data"":[0,1,2,3,4]}"));
        MyPoco? result = await JsonSerializer.DeserializeAsync<MyPoco>(stream)!;
        await foreach (int item in result!.Data!)
        {
            Console.WriteLine(item);
        }
    }
}
// output:
//0
//1
//2
//3
//4

이 예제에서 역직렬 변환기는 역직렬화된 개체를 반환하기 전에 메모리의 모든 IAsyncEnumerable<T> 콘텐츠를 버퍼링합니다. 역직렬 변환기는 결과를 반환하기 전에 전체 JSON 페이로드를 읽어야 하기 때문에 이 동작이 필요합니다.

System.Collections.Immutable 네임스페이스

* 유형에 대한 지원 왕복을 참조하세요.

† 지원되는 키 형식참조하세요.

System.Collections.Specialized 네임스페이스

* BitVector32 역직렬화되면 공용 setter가 없으므로 Data 속성은 건너뜁집니다. 예외가 throw되지 않습니다.

System.Collections.Concurrent 네임스페이스

* 유형에 대한 지원 왕복을 참조하세요.

† 지원되는 키 형식참조하세요.

System.Collections.ObjectModel 네임스페이스

*string 키가 지원되지 않습니다.

사용자 지정 컬렉션

이전 네임스페이스 중 하나에 없는 컬렉션 형식은 사용자 지정 컬렉션으로 간주됩니다. 이러한 형식에는 ASP.NET Core에서 정의한 사용자 정의 형식 및 형식이 포함되었습니다. 예를 들어 Microsoft.Extensions.Primitives 이 그룹에 있습니다.

요소 형식이 지원되는 한 모든 사용자 지정 컬렉션(IEnumerable파생)은 serialization에 대해 지원됩니다.

역직렬화 지원

사용자 지정 컬렉션은 다음과 같은 경우 역직렬화에 대해 지원됩니다.

• 인터페이스 또는 추상이 아닙니다.

• 매개 변수가 없는 생성자가 있습니다.

• JsonSerializer지원되는 요소 형식을 포함합니다.

• 다음 인터페이스 또는 클래스 중 하나 이상을 구현하거나 상속합니다.

  • ConcurrentQueue<T>
  • ConcurrentStack<T> *
  • ICollection<T>
  • IDictionary
  • IDictionary<TKey,TValue> †
  • IList
  • IList<T>
  • Queue
  • Queue<T>
  • Stack *
  • Stack<T> *

  * 유형에 대한 지원 왕복을 참조하세요.

  † 지원되는 키 형식참조하세요.

알려진 문제

다음 사용자 지정 컬렉션에는 알려진 문제가 있습니다.

• ExpandoObject: dotnet/runtime#29690참조하세요.
• DynamicObject: dotnet/runtime#1808참조하세요.
• DataTable: dotnet/docs#21366참조하세요.
• Microsoft.AspNetCore.Http.FormFile: dotnet/runtime#1559참조하세요.
• Microsoft.AspNetCore.Http.IFormCollection: dotnet/runtime#1559참조하세요.

알려진 문제에 대한 자세한 내용은 열린 문제를 참조하세요.

지원되는 키 형식

Dictionary 및 SortedList 형식의 키로 사용되는 경우 다음 형식은 기본 제공 지원을 제공합니다.

• Boolean
• Byte
• DateTime
• DateTimeOffset
• Decimal
• Double
• Enum
• Guid
• Int16
• Int32
• Int64
• Object(serialization에만 해당하며 런타임 형식이 이 목록에서 지원되는 형식 중 하나인 경우에만)
• SByte
• Single
• String
• TimeSpan
• UInt16
• UInt32
• UInt64
• Uri
• Version

또한 JsonConverter<T>.WriteAsPropertyName(Utf8JsonWriter, T, JsonSerializerOptions) 및 JsonConverter<T>.ReadAsPropertyName(Utf8JsonReader, Type, JsonSerializerOptions) 메서드를 사용하면 선택한 모든 형식에 대한 사전 키 지원을 추가할 수 있습니다.

지원되지 않는 형식

serialization에는 다음 형식이 지원되지 않습니다.

• System.Type 및 System.Reflection.MemberInfo
• 일반적으로 ReadOnlySpan<T>, Span<T>및 ref 구조체
• 대리자 형식
• IntPtr 및 UIntPtr

System.Data 네임스페이스

System.Data 네임스페이스에는 DataSet, DataTable및 관련 형식에 대한 기본 제공 변환기가 없습니다. 보안 지침설명한 대로 신뢰할 수 없는 입력에서 이러한 형식을 역직렬화하는 것은 안전하지 않습니다. 그러나 이러한 형식을 지원하는 사용자 지정 변환기를 작성할 수 있습니다. DataTable직렬화하고 역직렬화하는 샘플 사용자 지정 변환기 코드는 RoundtripDataTable.cs참조하세요.

참고 항목

• 초기화된 속성 채우기
• System.Text.Json 개요
• System.Text.Json API 참조
• System.Text.Json. serialization API 참조