Mode pembuatan sumber dalam System.Text.Json

Pembuatan sumber dapat digunakan dalam dua mode: berbasis metadata dan pengoptimalan serialisasi. Artikel ini menjelaskan berbagai mode.

Untuk informasi tentang cara menggunakan mode pembuatan sumber, lihat Cara menggunakan pembuatan sumber di System.Text.Json.

Mode berbasis metadata

Anda dapat menggunakan pembuatan sumber untuk memindahkan proses pengumpulan metadata dari runtime ke waktu kompilasi. Selama kompilasi, metadata dikumpulkan dan file kode sumber dihasilkan. File kode sumber yang dihasilkan secara otomatis dikompilasi sebagai bagian integral dari aplikasi. Teknik ini menghilangkan pengumpulan metadata runtime, yang meningkatkan performa serialisasi dan deserialisasi.

Peningkatan performa yang disediakan oleh generasi sumber dapat menjadi signifikan. Misalnya, hasil pengujian telah menunjukkan pengurangan waktu mulai hingga 40% atau lebih, pengurangan memori privat, peningkatan kecepatan throughput (dalam mode pengoptimalan serialisasi), dan pengurangan ukuran aplikasi.

Anggota dan konstruktor non-publik

Secara bawaan, baik mode refleksi maupun mode pembuatan kode sumber hanya menyertakan properti dan bidang public dalam kontrak serialisasi.

Mulai dari .NET 11, pembuatan kode sumber mendukung anggota yang secara eksplisit Anda tandai dengan atribut [JsonInclude]. Anggota dapat berupa private, , internalatau protected. Ini juga mendukung private, , internaldan protected aksesor pada properti yang Anda tandai dengan [JsonInclude]. Pembuatan sumber juga mendukung konstruktor yang tidak dapat diakses yang ditandai dengan [JsonConstructor].

Pada .NET 11, aksesor yang dihasilkan menggunakan UnsafeAccessorAttribute.

Metode setter yang dihasilkan sumber untuk properti khusus init hanya dijalankan saat payload JSON berisi properti tersebut. Properti khusus init yang tidak disertakan dalam payload tetap menggunakan nilai dari penginisialisasi propertinya.

Dalam .NET 10 dan versi yang lebih lama, pembuatan sumber memiliki batasan berikut:

  • Pembuatan kode sumber tidak mendukung anggota atau aksesor private atau protected. Jika Anda menandai anggota seperti itu dengan [JsonInclude], serializer akan melempar NotSupportedException saat runtime.
  • Pembuatan kode sumber mendukung anggota dan pengakses internal hanya jika keduanya dapat diakses oleh JsonSerializerContext yang dihasilkan dalam assembly yang sama.
  • Pembuatan sumber tidak mendukung konstruktor yang tidak dapat diakses oleh konteks yang dihasilkan, bahkan ketika Anda menandainya dengan [JsonConstructor].

Masalah umum

Untuk informasi tentang masalah lain yang diketahui dengan pembuatan sumber, lihat masalah GitHub yang diberi label "generator sumber" di repositori dotnet/runtime.

Mode pengoptimalan serialisasi (jalur cepat)

JsonSerializer memiliki banyak fitur yang menyesuaikan output serialisasi, seperti kebijakan penamaan dan mempertahankan referensi. Dukungan untuk semua fitur tersebut menyebabkan beberapa beban kinerja. Pembuatan sumber dapat meningkatkan performa serialisasi dengan menghasilkan kode yang dioptimalkan yang menggunakan Utf8JsonWriter secara langsung.

Mode pengoptimalan serialisasi memancarkan metode serialisasi jalur cepat tetapi bukan metadata serialisasi. Serialisasi jalur cepat dibatasi dalam apa yang dapat dilakukannya; ini tidak mendukung serialisasi asinkron atau mode deserialisasi apa pun.

Selain itu, kode yang dioptimalkan tidak mendukung semua fitur serialisasi yang JsonSerializer mendukung. Serializer mendeteksi apakah kode yang dioptimalkan dapat digunakan dan kembali ke kode serialisasi default jika opsi yang tidak didukung ditentukan. Misalnya, JsonNumberHandling.AllowReadingFromString tidak berlaku untuk menulis, jadi menentukan opsi ini tidak menyebabkan fallback ke kode default.

Tabel berikut ini memperlihatkan opsi mana dalam JsonSerializerOptions yang didukung oleh serialisasi jalur cepat:

Opsi serialisasi Didukung untuk jalur cepat
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

(Opsi berikut tidak didukung karena hanya berlaku untuk deserialisasi: PropertyNameCaseInsensitive, , ReadCommentHandlingdan UnknownTypeHandling.)

Tabel berikut menunjukkan atribut mana yang didukung oleh serialisasi jalur cepat:

Atribut Didukung untuk jalur cepat
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

Jika opsi atau atribut yang tidak didukung ditentukan untuk jenis, serializer kembali ke mode metadata, dengan asumsi bahwa generator sumber telah dikonfigurasi untuk menghasilkan metadata. Dalam hal ini, kode yang dioptimalkan tidak digunakan saat menserialisasikan jenis tersebut, tetapi mungkin digunakan untuk jenis lain. Oleh karena itu, penting untuk melakukan pengujian performa dengan opsi dan beban kerja Anda untuk menentukan berapa banyak manfaat yang benar-benar dapat Anda dapatkan dari mode pengoptimalan serialisasi. Selain itu, kemampuan untuk kembali ke JsonSerializer kode memerlukan mode metadata. Jika Anda hanya memilih mode pengoptimalan serialisasi, serialisasi mungkin gagal untuk jenis atau opsi yang perlu kembali ke JsonSerializer kode.

Lihat juga

  • Terakhir diperbarui pada