Cara menggunakan JSONOBJECT.TOSTRING pada JavaScript

Lompati ke konten utama

Browser ini sudah tidak didukung.

Mutakhirkan ke Microsoft Edge untuk memanfaatkan fitur, pembaruan keamanan, dan dukungan teknis terkini.

Cara menulis pengonversi kustom untuk serialisasi JSON (penyusunan) di .NET

• Artikel
• 09/29/2022
• 25 menit untuk membaca

Dalam artikel ini

Artikel ini menunjukkan cara membuat pengonversi kustom untuk kelas serialisasi JSON yang disediakan di namespace layanan System.Text.Json. Untuk pengenalan System.Text.Json, lihat Cara membuat serialisasi dan deserialisasi JSON di .NET.

Pengonversi adalah kelas yang mengonversi objek atau nilai ke dan dari JSON. Namespace layanan System.Text.Json memiliki pengonversi bawaan untuk sebagian besar jenis primitif yang memetakan ke primitif JavaScript. Anda dapat menulis pengonversi kustom:

• Untuk mengganti perilaku pengonversi bawaan default. Misalnya, Anda mungkin ingin nilai DateTime diwakili oleh format mm/dd/yyyy. Secara default, ISO 8601-1:2019 didukung, termasuk profil RFC 3339. Untuk informasi selengkapnya, lihat Dukungan DateTime dan DateTimeOffset di System.Text.Json.
• Untuk mendukung jenis nilai kustom. Misalnya, struktur PhoneNumber.

Anda juga dapat menulis pengonversi kustom untuk menyesuaikan atau memperluas System.Text.Json dengan fungsionalitas yang tidak disertakan dalam rilis saat ini. Skenario berikut dibahas nanti dalam artikel ini:

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.
• Mendukung deserialisasi nilai string enum.
• Menggunakan pengonversi sistem default.

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.
• Mendukung deserialisasi nilai string enum.

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung Kamus dengan kunci non-string.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.

Dalam kode yang Anda tulis untuk pengonversi kustom, perhatikan penalti performa substansial untuk menggunakan instans JsonSerializerOptions baru. Untuk informasi selengkapnya, lihat Menggunakan kembali instans JsonSerializerOptions.

Visual Basic tidak dapat digunakan untuk menulis pengonversi kustom tetapi dapat memanggil pengonversi yang diimplementasikan di pustaka C#. Untuk informasi selengkapnya, lihat dukungan Visual Basic.

Pola pengonversi kustom

Ada dua pola untuk membuat pengonversi kustom: pola dasar dan pola pabrik. Pola pabrik adalah untuk pengonversi yang menangani jenis Enum atau generik terbuka. Pola dasarnya adalah untuk jenis generik dan non-generik tertutup. Misalnya, non-generik untuk jenis berikut memerlukan pola pabrik:

• Dictionary
• Enum
• List

Beberapa contoh jenis yang dapat ditangani oleh pola dasar meliputi:

• Dictionary
• WeekdaysEnum
• List
• DateTime
• Int32

Pola dasar menciptakan kelas yang dapat menangani satu jenis. Pola pabrik menciptakan kelas yang menentukan, pada waktu berjalan, jenis tertentu mana yang diperlukan dan secara dinamis membuat pengonversi yang sesuai.

Sampel pengonversi dasar

Sampel berikut adalah pengonversi yang menimpa serialisasi default untuk jenis data yang ada. Pengonversi menggunakan format mm/dd/yyyy untuk properti DateTimeOffset.

using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class DateTimeOffsetJsonConverter : JsonConverter
    {
        public override DateTimeOffset Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options) =>
                DateTimeOffset.ParseExact(reader.GetString()!,
                    "MM/dd/yyyy", CultureInfo.InvariantCulture);

        public override void Write(
            Utf8JsonWriter writer,
            DateTimeOffset dateTimeValue,
            JsonSerializerOptions options) =>
                writer.WriteStringValue(dateTimeValue.ToString(
                    "MM/dd/yyyy", CultureInfo.InvariantCulture));
    }
}

Sampel pengonversi pola pabrik

Kode berikut menunjukkan pengonversi kustom yang berfungsi dengan Dictionary. Kode mengikuti pola pabrik karena parameter jenis generik pertama adalah Enum dan yang kedua terbuka. Metode CanConvert hanya menampilkan true untuk Dictionary dengan dua parameter generik, yang pertama adalah jenis Enum. Pengonversi dalam akan mendapatkan pengonversi yang ada untuk menangani jenis apa pun yang disediakan pada durasi untuk TValue.

using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    public class DictionaryTKeyEnumTValueConverter : JsonConverterFactory
    {
        public override bool CanConvert(Type typeToConvert)
        {
            if (!typeToConvert.IsGenericType)
            {
                return false;
            }

            if (typeToConvert.GetGenericTypeDefinition() != typeof(Dictionary<,>))
            {
                return false;
            }

            return typeToConvert.GetGenericArguments()[0].IsEnum;
        }

        public override JsonConverter CreateConverter(
            Type type,
            JsonSerializerOptions options)
        {
            Type keyType = type.GetGenericArguments()[0];
            Type valueType = type.GetGenericArguments()[1];

            JsonConverter converter = (JsonConverter)Activator.CreateInstance(
                typeof(DictionaryEnumConverterInner<,>).MakeGenericType(
                    new Type[] { keyType, valueType }),
                BindingFlags.Instance | BindingFlags.Public,
                binder: null,
                args: new object[] { options },
                culture: null)!;

            return converter;
        }

        private class DictionaryEnumConverterInner :
            JsonConverter> where TKey : struct, Enum
        {
            private readonly JsonConverter _valueConverter;
            private readonly Type _keyType;
            private readonly Type _valueType;

            public DictionaryEnumConverterInner(JsonSerializerOptions options)
            {
                // For performance, use the existing converter if available.
                _valueConverter = (JsonConverter)options
                    .GetConverter(typeof(TValue));

                // Cache the key and value types.
                _keyType = typeof(TKey);
                _valueType = typeof(TValue);
            }

            public override Dictionary Read(
                ref Utf8JsonReader reader,
                Type typeToConvert,
                JsonSerializerOptions options)
            {
                if (reader.TokenType != JsonTokenType.StartObject)
                {
                    throw new JsonException();
                }

                var dictionary = new Dictionary();

                while (reader.Read())
                {
                    if (reader.TokenType == JsonTokenType.EndObject)
                    {
                        return dictionary;
                    }

                    // Get the key.
                    if (reader.TokenType != JsonTokenType.PropertyName)
                    {
                        throw new JsonException();
                    }

                    string? propertyName = reader.GetString();

                    // For performance, parse with ignoreCase:false first.
                    if (!Enum.TryParse(propertyName, ignoreCase: false, out TKey key) &&
                        !Enum.TryParse(propertyName, ignoreCase: true, out key))
                    {
                        throw new JsonException(
                            $"Unable to convert \"{propertyName}\" to Enum \"{_keyType}\".");
                    }

                    // Get the value.
                    TValue value;
                    if (_valueConverter != null)
                    {
                        reader.Read();
                        value = _valueConverter.Read(ref reader, _valueType, options)!;
                    }
                    else
                    {
                        value = JsonSerializer.Deserialize(ref reader, options)!;
                    }

                    // Add to dictionary.
                    dictionary.Add(key, value);
                }

                throw new JsonException();
            }

            public override void Write(
                Utf8JsonWriter writer,
                Dictionary dictionary,
                JsonSerializerOptions options)
            {
                writer.WriteStartObject();

                foreach ((TKey key, TValue value) in dictionary)
                {
                    var propertyName = key.ToString();
                    writer.WritePropertyName
                        (options.PropertyNamingPolicy?.ConvertName(propertyName) ?? propertyName);

                    if (_valueConverter != null)
                    {
                        _valueConverter.Write(writer, value, options);
                    }
                    else
                    {
                        JsonSerializer.Serialize(writer, value, options);
                    }
                }

                writer.WriteEndObject();
            }
        }
    }
}

Langkah-langkah untuk mengikuti pola dasar

Langkah-langkah berikut menjelaskan cara membuat pengonversi dengan mengikuti pola dasar:

• Buat kelas yang berasal dari JsonConverter dengan T adalah jenis yang akan diserialisasikan dan dideserialisasi.
• Ganti metode Read untuk mendeserialisasi JSON yang masuk dan mengonversinya menjadi jenis T. Gunakan Utf8JsonReader yang diteruskan ke metode untuk membaca JSON. Anda tidak perlu khawatir tentang penanganan data parsial, karena pembuat serialisasi meneruskan semua data untuk cakupan JSON saat ini. Jadi tidak perlu memanggil Skip atau TrySkip, atau memvalidasi bahwa Read menampilkan true.
• Ganti metode Write untuk menserialisasi objek yang masuk jenis T. Gunakan Utf8JsonWriter yang diteruskan ke metode untuk menulis JSON.
• Ganti metode CanConvert hanya jika perlu. Implementasi default akan menampilkan true jika jenis yang akan dikonversi berjenis T. Oleh karena itu, pengonversi yang hanya mendukung jenis T tidak perlu mengganti metode ini. Untuk contoh pengonversi yang memang perlu mengganti metode ini, lihat bagian deserialisasi polimorfik nanti dalam artikel ini.

Anda dapat merujuk ke kode sumber pengonversi bawaan sebagai implementasi referensi untuk menulis pengonversi kustom.

Langkah-langkah untuk mengikuti pola pabrik

Langkah-langkah berikut menjelaskan cara membuat pengonversi dengan mengikuti pola pabrik:

• Buat kelas yang berasal dari JsonConverterFactory.
• Ganti metode CanConvert untuk menampilkan true jika jenis yang akan dikonversi adalah salah satu yang dapat ditangani pengonversi. Misalnya, jika pengonversi untuk List pengonversi tersebut mungkin hanya menangani List, List, dan List.
• Ganti metode CreateConverter untuk menampilkan instans kelas pengonversi yang akan menangani jenis yang akan dikonversi yang disediakan saat durasi.
• Buat kelas pengonversi yang digunakan metode CreateConverter.

Pola pabrik diperlukan untuk generik terbuka karena kode untuk mengonversi objek ke dan dari string tidak sama untuk semua jenis. Pengonversi untuk jenis generik terbuka (List, misalnya) harus membuat pengonversi untuk jenis generik tertutup (List, misalnya) di belakang layar. Kode harus ditulis untuk menangani setiap jenis generik tertutup yang dapat ditangani pengonversi.

Jenis Enum mirip dengan jenis generik terbuka: pengonversi untuk Enum harus membuat pengonversi untuk Enum tertentu (WeekdaysEnum, misalnya) di belakang layar.

Penggunaan Utf8JsonReader dalam metode Read

Jika pengonversi Anda mengonversi objek JSON, Utf8JsonReader akan diposisikan pada token objek awal saat metode Read dimulai. Anda lalu harus membaca semua token dalam objek tersebut dan keluar dari metode dengan pembaca yang diposisikan pada token objek akhir yang sesuai. Jika Anda membaca di luar akhir objek, atau jika Anda berhenti sebelum mencapai token akhir yang sesuai, Anda mendapatkan pengecualian JsonException yang menunjukkan bahwa:

Pengonversi 'ConverterName' membaca terlalu banyak atau tidak cukup.

Misalnya, lihat pengonversi sampel pola pabrik sebelumnya. Metode Read dimulai dengan memastikan bahwa pembaca diposisikan pada token objek awal. Ini membaca sampai menemukan bahwa ini diposisikan pada token objek akhir berikutnya. Ini berhenti pada token objek akhir berikutnya karena tidak ada token objek mulai intervensi yang akan menunjukkan objek dalam objek. Aturan yang sama tentang token awal dan token akhir berlaku jika Anda mengonversi array. Misalnya, lihat sampel pengonversi Stack nanti dalam artikel ini.

Penanganan kesalahan

Pembuat serialisasi menyediakan penanganan khusus untuk jenis pengecualian JsonException dan NotSupportedException.

JsonException

Jika Anda menampilkan JsonException tanpa pesan, pembuat serialisasi membuat pesan yang menyertakan jalur ke bagian JSON yang menyebabkan kesalahan. Misalnya, pernyataan throw new JsonException() menghasilkan pesan kesalahan seperti contoh berikut:

Unhandled exception. System.Text.Json.JsonException:
The JSON value could not be converted to System.Object.
Path: $.Date | LineNumber: 1 | BytePositionInLine: 37.

Jika Anda memberikan pesan (misalnya, throw new JsonException("Error occurred")), pembuat serialisasi tetap mengatur properti Path, LineNumber, dan BytePositionInLine.

NotSupportedException

Jika Anda menampilkan NotSupportedException, Anda akan mendapatkan informasi jalur dalam pesan kapan saja. Jika Anda memberikan pesan, informasi jalur akan ditambahkan ke dalamnya. Misalnya, pernyataan throw new NotSupportedException("Error occurred.") menghasilkan pesan kesalahan seperti contoh berikut:

Error occurred. The unsupported member type is located on type
'System.Collections.Generic.Dictionary`2[Samples.SummaryWords,System.Int32]'.
Path: $.TemperatureRanges | LineNumber: 4 | BytePositionInLine: 24

Kapan harus menampilkan jenis pengecualian

Jika payload JSON berisi token yang tidak valid untuk jenis yang dideserialisasi, tampilkan JsonException.

Jika Anda ingin melarang jenis tertentu, tampilkan NotSupportedException. Pengecualian inilah yang secara otomatis dilemparkan oleh pembuat serialisasi untuk jenis yang tidak didukung. Misalnya, System.Type tidak didukung karena alasan keamanan, jadi upaya untuk mendeserialisasinya akan menghasilkan NotSupportedException.

Anda dapat menampilkan pengecualian lain sesuai kebutuhan, tetapi tidak secara otomatis menyertakan informasi jalur JSON.

Mendaftarkan pengonversi kustom

Daftarkan pengonversi kustom agar metode Serialize dan Deserialize menggunakannya. Pilih salah satu pendekatan berikut:

• Tambahkan instans kelas pengonversi ke kumpulan JsonSerializerOptions.Converters.
• Terapkan atribut [JsonConverter] ke properti yang memerlukan pengonversi kustom.
• Terapkan atribut [JsonConverter] ke kelas atau struktur yang mewakili jenis nilai kustom.

Sampel pendaftaran - Kumpulan pengonversi

Berikut ini contoh yang menjadikan DateTimeOffsetJsonConverter sebagai default untuk properti jenis DateTimeOffset:

var serializeOptions = new JsonSerializerOptions
{
    WriteIndented = true,
    Converters =
    {
        new DateTimeOffsetJsonConverter()
    }
};

jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

Misalkan Anda melakukan serialisasi instans dari jenis berikut:

public class WeatherForecast
{
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

Berikut ini contoh output JSON yang menunjukkan pengonversi kustom digunakan:

{
  "Date": "08/01/2019",
  "TemperatureCelsius": 25,
  "Summary": "Hot"
}

Kode berikut menggunakan pendekatan yang sama untuk mendeserialisasi menggunakan pengonversi kustom DateTimeOffset:

var deserializeOptions = new JsonSerializerOptions();
deserializeOptions.Converters.Add(new DateTimeOffsetJsonConverter());
weatherForecast = JsonSerializer.Deserialize(jsonString, deserializeOptions)!;

Sampel pendaftaran - [JsonConverter] di properti

Kode berikut memilih pengonversi kustom untuk properti Date:

public class WeatherForecastWithConverterAttribute
{
    [JsonConverter(typeof(DateTimeOffsetJsonConverter))]
    public DateTimeOffset Date { get; set; }
    public int TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

Kode untuk serialisasi WeatherForecastWithConverterAttribute tidak memerlukan penggunaan JsonSerializeOptions.Converters:

var serializeOptions = new JsonSerializerOptions
{
    WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);

Kode untuk deserialisasi juga tidak memerlukan penggunaan Converters:

weatherForecast = JsonSerializer.Deserialize(jsonString)!;

Sampel pendaftaran - [JsonConverter] pada jenis

Berikut ini kode yang membuat struktur dan menerapkan atribut [JsonConverter] ke struktur tersebut:

using System.Text.Json.Serialization;

namespace SystemTextJsonSamples
{
    [JsonConverter(typeof(TemperatureConverter))]
    public struct Temperature
    {
        public Temperature(int degrees, bool celsius)
        {
            Degrees = degrees;
            IsCelsius = celsius;
        }

        public int Degrees { get; }
        public bool IsCelsius { get; }
        public bool IsFahrenheit => !IsCelsius;

        public override string ToString() =>
            $"{Degrees}{(IsCelsius ? "C" : "F")}";

        public static Temperature Parse(string input)
        {
            int degrees = int.Parse(input.Substring(0, input.Length - 1));
            bool celsius = input.Substring(input.Length - 1) == "C";

            return new Temperature(degrees, celsius);
        }
    }
}

Berikut adalah pengonversi kustom untuk struktur sebelumnya:

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

namespace SystemTextJsonSamples
{
    public class TemperatureConverter : JsonConverter
    {
        public override Temperature Read(
            ref Utf8JsonReader reader,
            Type typeToConvert,
            JsonSerializerOptions options) =>
                Temperature.Parse(reader.GetString()!);

        public override void Write(
            Utf8JsonWriter writer,
            Temperature temperature,
            JsonSerializerOptions options) =>
                writer.WriteStringValue(temperature.ToString());
    }
}

Atribut [JsonConverter] pada struktur mendaftarkan pengonversi kustom sebagai default untuk properti jenis Temperature. Pengonversi secara otomatis digunakan pada properti TemperatureCelsius jenis berikut saat Anda menserialisasikan atau mendeserialisasikannya:

public class WeatherForecastWithTemperatureStruct
{
    public DateTimeOffset Date { get; set; }
    public Temperature TemperatureCelsius { get; set; }
    public string? Summary { get; set; }
}

Prioritas pendaftaran pengonversi

Selama serialisasi atau deserialisasi, pengonversi dipilih untuk setiap elemen JSON dalam urutan berikut, tercantum dari prioritas tertinggi ke terendah:

• [JsonConverter] diterapkan ke properti.
• Pengonversi ditambahkan ke kumpulan Converters.
• [JsonConverter] diterapkan ke jenis nilai kustom atau POCO.

Jika beberapa pengonversi kustom untuk jenis terdaftar dalam kumpulan Converters, pengonversi pertama yang menampilkan true untuk CanConvert akan digunakan.

Pengonversi bawaan hanya akan dipilih jika tidak ada pengonversi kustom yang berlaku yang terdaftar.

Sampel pengonversi untuk skenario umum

Bagian berikut menyediakan sampel pengonversi yang membahas beberapa skenario umum yang tidak ditangani oleh fungsionalitas bawaan.

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.
• Mendukung deserialisasi nilai string enum.
• Menggunakan pengonversi sistem default.

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.
• Mendukung deserialisasi nilai string enum.

• Deserialisasi jenis yang disimpulkan ke properti objek.
• Mendukung Kamus dengan kunci non-string.
• Mendukung deserialisasi polimorfik.
• Mendukung komunikasi dua arah untuk Stack.

Untuk pengonversi sampel DataTable, lihat Jenis koleksi yang didukung.

Deserialisasi jenis yang disimpulkan ke properti objek

Saat deserialisasi ke properti jenis object, objek JsonElement akan dibuat. Alasannya adalah bahwa pembuat deserialisasi tidak tahu jenis CLR apa yang harus dibuat, dan tidak mencoba menebak. Misalnya, jika properti JSON memiliki "true", pembuat deserialisasi tidak menyimpulkan bahwa nilainya adalah Boolean, dan jika elemen memiliki "01/01/2019", pembuat deserialisasi tidak menyimpulkan bahwa itu adalah DateTime.

Inferensi jenis bisa tidak akurat. Jika pembuat deserialisasi mengurai angka JSON yang tidak memiliki titik desimal sebagai long, yang dapat mengakibatkan masalah di luar rentang jika nilai awalnya diserialisasikan sebagai ulong atau BigInteger. Mengurai angka yang memiliki titik desimal sebagai double mungkin kehilangan presisi jika angka awalnya diserialisasikan sebagai decimal.

Untuk skenario yang memerlukan inferensi jenis, kode berikut menunjukkan pengonversi kustom untuk properti object. Kode akan mengonversi:

• true dan false ke Boolean
• Angka tanpa desimal ke long
• Angka dengan desimal ke double
• Tanggal ke DateTime
• String ke string
• Segala sesuatu yang lain ke JsonElement

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

namespace CustomConverterInferredTypesToObject
{
    public class ObjectToInferredTypesConverter : JsonConverter