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

  • 아티클

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

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

메타데이터 기반 모드

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

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

알려진 문제

serialization 모드에서는 public 속성 및 필드만 기본적으로 지원됩니다. 그러나 리플렉션 모드는 private접근자 사용을 지원하지만 소스 생성 모드는 접근자를 지원하지 않습니다. 예를 들어 private setter 또는 getter가 있고 리플렉션 모드로 직렬화되는 속성에 JsonInclude 특성을 적용할 수 있습니다. 소스 생성 모드는 public 속성의 public 또는 internal 접근자만 지원합니다. public이 아닌 접근자에서 [JsonInclude]를 설정하고 원본 생성 모드를 선택하면 런타임에 NotSupportedException이 throw됩니다.

serialization 모드에서는 public 속성 및 필드만 기본적으로 지원됩니다. 그러나 리플렉션 모드는 private 멤버 및 private접근자 사용을 지원하는 반면 원본 생성 모드는 지원하지 않습니다. 예를 들어, JsonInclude 특성을 private 특성이나 private setter 또는 getter가 있는 속성에 적용하면 리플렉션 모드에서 직렬화됩니다. 원본 생성 모드는 public 속성의 public 또는 internal 멤버와 public 또는 internal 접근자만 지원합니다. private 멤버 또는 접근자에 [JsonInclude]를 설정하고 원본 생성 모드를 선택하면 런타임 시 NotSupportedException이 throw됩니다.

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

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

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

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

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

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

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

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

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

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

참고 항목