Bagikan melalui

Mode pembuatan sumber dalam System.Text.Json

  • Artikel

Pembuatan sumber dapat digunakan dalam dua mode: pengoptimalan berbasis metadata dan 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 durasi 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 run-time, yang meningkatkan performa serialisasi dan deserialisasi.

Peningkatan performa yang disediakan oleh pembuatan sumber dapat menjadi substansial. 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.

Masalah umum

Hanya public properti dan bidang yang didukung secara default dalam mode serialisasi. Namun, mode refleksi mendukung penggunaan private aksesor, sementara mode pembuatan sumber tidak. Misalnya, Anda dapat menerapkan atribut JsonInclude ke properti yang memiliki private setter atau getter dan akan diserialisasikan dalam mode pantulan. Mode pembuatan sumber hanya public mendukung atau internal pengaktor public properti. Jika Anda mengatur [JsonInclude] aksesor non-publik dan memilih mode pembuatan sumber, akan NotSupportedException dilemparkan pada waktu proses.

Hanya public properti dan bidang yang didukung secara default dalam mode serialisasi. Namun, mode refleksi mendukung penggunaan private anggota dan private aksesor, sementara mode pembuatan sumber tidak. Misalnya, jika Anda menerapkan atribut JsonInclude ke private properti atau properti yang memiliki private setter atau getter, itu akan diserialisasikan dalam mode refleksi. Mode pembuatan sumber hanya public mendukung atau internal anggota dan public atau internal aksesor public properti. Jika Anda mengatur [JsonInclude] private anggota atau aksesor dan memilih mode pembuatan sumber, akan NotSupportedException dilemparkan pada waktu proses.

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 overhead performa. Pembuatan sumber dapat meningkatkan performa serialisasi dengan menghasilkan kode yang dioptimalkan yang menggunakan Utf8JsonWriter secara langsung.

Kode yang dioptimalkan tidak mendukung semua fitur serialisasi yang didukung JsonSerializer. 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 yang JsonSerializerOptions 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 dapat 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 pengumpulan metadata. Jika Anda hanya memilih mode pengoptimalan serialisasi, serialisasi mungkin gagal untuk jenis atau opsi yang perlu kembali ke JsonSerializer kode.

Lihat juga