System.Text.Json의 원본 생성 모드

원본 생성은 메타데이터 기반 및 serialization 최적화의 두 가지 모드에서 사용할 수 있습니다. 이 문서에서는 다양한 모드에 대해 설명합니다.

원본 생성 모드를 사용하는 방법에 대한 내용은 System.Text.Json에서 원본 생성을 사용하는 방법을 참조하세요.

메타데이터 기반 모드

원본 생성을 사용하여 메타데이터 수집 프로세스를 런타임에서 컴파일 시간으로 이동할 수 있습니다. 컴파일하는 동안 메타데이터가 수집되고 소스 코드 파일이 생성됩니다. 생성된 소스 코드 파일은 애플리케이션의 필수 부분으로 자동으로 컴파일됩니다. 이 기술은 런타임 메타데이터 컬렉션을 제거하여 serialization 및 deserialization의 성능을 향상시킵니다.

원본 생성을 통해 상당한 성능 향상 효과를 얻을 수 있습니다. 예를 들어 테스트 결과에는 최대 40% 이상의 시작 시간 감소, 프라이빗 메모리 감소, 처리량 속도 증가(serialization 최적화 모드) 및 앱 크기 감소가 표시됩니다.

비공용 멤버 및 생성자

기본적으로 리플렉션 모드와 소스 생성 모드에는 serialization 계약의 속성과 필드만 public 포함됩니다.

.NET 11부터 원본 생성은 [JsonInclude] 특성으로 명시적으로 표시하는 멤버를 지원합니다. 멤버는 private, internal 또는 protected일 수 있습니다. internal로 표시한 속성에서 [JsonInclude], protected, 및 private 접근자도 지원합니다. 원본 생성은 [JsonConstructor]로 표시된 액세스할 수 없는 생성자도 지원합니다.

.NET 11에서는 생성된 접근자가 UnsafeAccessorAttribute를 사용합니다.

init 전용 속성에 대한 소스 생성된 setter는 JSON 페이로드에 해당 속성이 포함된 경우에만 호출됩니다. 페이로드에서 생략된 init-only 속성은 속성 이니셜라이저의 값을 유지합니다.

.NET 10 이전 버전에서는 원본 생성에 다음과 같은 제한 사항이 있습니다.

• 소스 생성은 protected 또는 private 멤버나 접근자를 지원하지 않습니다. 이러한 멤버를 [JsonInclude]로 지정하면 serializer가 런타임에 NotSupportedException을 발생시킵니다.
• 원본 생성은 internal 동일한 어셈블리에서 생성된 JsonSerializerContext 멤버에 액세스할 수 있는 경우에만 멤버 및 접근자를 지원합니다.
• 소스 생성은 [JsonConstructor]로 표시하더라도 생성된 컨텍스트에서 액세스할 수 없는 생성자를 지원하지 않습니다.

알려진 문제

원본 생성과 관련된 다른 알려진 문제에 대한 내용은 dotnet/runtime 리포지토리에서 "source-generator" 레이블이 지정된 GitHub 이슈를 참조하세요.

직렬화 최적화(빠른 경로) 모드

JsonSerializer에는 명명 정책 및 참조 보존과 같이 직렬화 출력을 사용자 지정하는 많은 기능이 있습니다. 이러한 모든 기능을 지원하면 성능 오버헤드가 발생합니다. 원본 생성은 Utf8JsonWriter를 직접 사용하는 최적화된 코드를 생성하여 serialization 성능을 향상시킬 수 있습니다.

Serialization 최적화 모드는 빠른 경로 serialization 메서드를 내보내지만 serialization 메타데이터는 내보내지 않습니다. 빠른 경로 직렬화는 수행할 수 있는 작업이 제한되어 있습니다. 비동기 직렬화나 역직렬화 모드를 지원하지 않습니다.

또한 최적화된 코드는 JsonSerializer이(가) 지원하는 모든 serialization 기능을 지원하지 않습니다. 직렬 변환기는 최적화된 코드를 사용할 수 있는지 여부를 검색하고 지원되지 않는 옵션이 지정된 경우 기본 serialization 코드로 돌아갑니다. 예를 들어, JsonNumberHandling.AllowReadingFromString은 쓰기에 적용할 수 없으므로 이 옵션을 지정해도 기본 코드로 대체되지 않습니다.

다음 표는 빠른 경로 직렬화에서 지원되는 JsonSerializerOptions의 옵션을 보여 줍니다.

직렬화 옵션	빠른 경로 지원
AllowTrailingCommas	✔️
Converters	❌
DefaultBufferSize	✔️
DefaultIgnoreCondition	✔️
DictionaryKeyPolicy	❌
Encoder	❌
IgnoreNullValues	❌
IgnoreReadOnlyFields	✔️
IgnoreReadOnlyProperties	✔️
IncludeFields	✔️
MaxDepth	✔️
NumberHandling	❌
PropertyNamingPolicy	✔️
ReferenceHandler	❌
TypeInfoResolver	✔️
WriteIndented	✔️

(다음 옵션은 역직렬화에만 적용되므로 지원되지 않습니다: PropertyNameCaseInsensitive, ReadCommentHandling 및 UnknownTypeHandling.)

다음 표는 빠른 경로 직렬화에서 지원되는 특성을 보여 줍니다.

특성	빠른 경로 지원
JsonConstructorAttribute	❌
JsonConverterAttribute	❌
JsonDerivedTypeAttribute	✔️
JsonExtensionDataAttribute	❌
JsonIgnoreAttribute	✔️
JsonIncludeAttribute	✔️
JsonNumberHandlingAttribute	❌
JsonPolymorphicAttribute	✔️
JsonPropertyNameAttribute	✔️
JsonPropertyOrderAttribute	✔️
JsonRequiredAttribute	✔️

지원되지 않는 옵션 또는 특성이 형식에 대해 지정된 경우 serializer는 원본 생성기가 메타데이터를 생성하도록 구성되었다고 가정하여 메타데이터 모드로 돌아갑니다. 이 경우 최적화된 코드는 해당 형식을 직렬화할 때 사용되지 않지만 다른 형식에 사용될 수 있습니다. 따라서 옵션 및 워크로드로 성능 테스트를 수행하여 serialization 최적화 모드에서 실제로 얻을 수 있는 이점을 파악하는 것이 중요합니다. 또한 JsonSerializer 코드로 돌아가려면 메타데이터 모드가 필요합니다. serialization 최적화 모드만 선택하면 JsonSerializer 코드로 대체해야 하는 형식이나 옵션에 대해 serialization이 실패할 수 있습니다.

참고 항목

• .NET의 JSON serialization 및 deserialization - 개요
• 라이브러리를 사용하는 방법