Cara menulis objek .NET sebagai JSON (berseri)

Artikel
09/07/2024

Artikel ini memperlihatkan cara menggunakan System.Text.Json namespace layanan untuk diserialisasikan ke JavaScript Object Notation (JSON). Jika Anda memindahkan kode yang ada dari Newtonsoft.Json, lihat Cara bermigrasi ke System.Text.Json.

Tip

Anda dapat menggunakan bantuan AI untuk membuat serialisasi ke JSON dengan GitHub Copilot.

Untuk menulis JSON ke string atau file, panggil metode JsonSerializer.Serialize.

Contoh serialisasi

Contoh berikut membuat JSON sebagai string:

using System.Text.Json;

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

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim jsonString As String

Output JSON diperkecil (spasi putih, lekukan, dan karakter baris baru dihapus) secara default.

Contoh berikut menggunakan kode sinkron untuk membuat file JSON:

using System.Text.Json;

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

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json"; 
            string jsonString = JsonSerializer.Serialize(weatherForecast);
            File.WriteAllText(fileName, jsonString);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(weatherForecast1)
File.WriteAllText(fileName, jsonString)

Contoh berikut menggunakan kode asinkron untuk membuat file JSON:

using System.Text.Json;

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

    public class Program
    {
        public static async Task Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string fileName = "WeatherForecast.json";
            await using FileStream createStream = File.Create(fileName);
            await JsonSerializer.SerializeAsync(createStream, weatherForecast);

            Console.WriteLine(File.ReadAllText(fileName));
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

Dim createStream As FileStream = File.Create(fileName)
Await JsonSerializer.SerializeAsync(createStream, weatherForecast1)

Contoh sebelumnya menggunakan inferensi jenis untuk jenis yang diserialkan. Kelebihan Serialize() membutuhkan parameter jenis generik:

using System.Text.Json;

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

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

            string jsonString = JsonSerializer.Serialize<WeatherForecast>(weatherForecast);

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{"Date":"2019-08-01T00:00:00-07:00","TemperatureCelsius":25,"Summary":"Hot"}

jsonString = JsonSerializer.Serialize(Of WeatherForecastWithPOCOs)(weatherForecast)

Anda juga dapat menggunakan GitHub Copilot untuk menghasilkan kode serialisasi untuk Anda. Untuk petunjuknya, lihat bagian Gunakan GitHub Copilot di artikel ini.

Perilaku serialisasi

Secara default, semua properti publik diserialkan. Anda dapat menentukan properti yang akan diabaikan. Anda juga dapat menyertakan anggota privat.
Encoder default keluar dari karakter non-ASCII, karakter peka HTML dalam rentang ASCII, dan karakter yang harus diloloskan berdasarkan spesifikasi RFC 8259 JSON.
Secara default, JSON diperkecil. Anda dapat mencetak JSON dengan cantik.
Secara default, casing nama JSON cocok dengan nama .NET. Anda dapat menyesuaikan casing nama JSON.
Secara default, referensi melingkar terdeteksi dan pengecualian muncul. Anda dapat mempertahankan referensi dan menangani referensi melingkar.
Secara default, bidang diabaikan. Anda dapat menyertakan bidang.

Saat Anda menggunakan System.Text.Json secara tidak langsung di aplikasi ASP.NET Core, beberapa perilaku default akan berbeda. Untuk informasi selengkapnya, lihat Default web untuk JsonSerializerOptions.

Jenis yang didukung meliputi:

Primitif .NET yang dipetakan ke primitif JavaScript, seperti jenis numerik, string, dan Boolean.
Objek CLR lama polos (POCO) yang ditentukan pengguna.
Array satu dimensi dan bergerigi (T[][]).
Koleksi dan kamus dari namespace berikut:
Untuk informasi selengkapnya, lihat Jenis koleksi yang didukung diSystem.Text.Json.

Anda dapat menerapkan pengonversi kustom untuk menangani jenis tambahan atau menyediakan fungsionalitas yang tidak didukung oleh pengonversi internal.

Berikut adalah contoh yang menunjukkan bagaimana kelas yang berisi properti koleksi dan jenis yang ditentukan pengguna dipembuatan serial:

using System.Text.Json;

namespace SerializeExtra
{
    public class WeatherForecast
    {
        public DateTimeOffset Date { get; set; }
        public int TemperatureCelsius { get; set; }
        public string? Summary { get; set; }
        public string? SummaryField;
        public IList<DateTimeOffset>? DatesAvailable { get; set; }
        public Dictionary<string, HighLowTemps>? TemperatureRanges { get; set; }
        public string[]? SummaryWords { get; set; }
    }

    public class HighLowTemps
    {
        public int High { get; set; }
        public int Low { get; set; }
    }

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot",
                SummaryField = "Hot",
                DatesAvailable = new List<DateTimeOffset>() 
                    { DateTime.Parse("2019-08-01"), DateTime.Parse("2019-08-02") },
                TemperatureRanges = new Dictionary<string, HighLowTemps>
                    {
                        ["Cold"] = new HighLowTemps { High = 20, Low = -10 },
                        ["Hot"] = new HighLowTemps { High = 60 , Low = 20 }
                    },
                SummaryWords = new[] { "Cool", "Windy", "Humid" }
            };

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

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot",
//  "DatesAvailable": [
//    "2019-08-01T00:00:00-07:00",
//    "2019-08-02T00:00:00-07:00"
//  ],
//  "TemperatureRanges": {
//    "Cold": {
//      "High": 20,
//      "Low": -10
//    },
//    "Hot": {
//    "High": 60,
//      "Low": 20
//    }
//  },
//  "SummaryWords": [
//    "Cool",
//    "Windy",
//    "Humid"
//  ]
//}

Public Class WeatherForecastWithPOCOs
    Public Property [Date] As DateTimeOffset
    Public Property TemperatureCelsius As Integer
    Public Property Summary As String
    Public SummaryField As String
    Public Property DatesAvailable As IList(Of DateTimeOffset)
    Public Property TemperatureRanges As Dictionary(Of String, HighLowTemps)
    Public Property SummaryWords As String()
End Class

Public Class HighLowTemps
    Public Property High As Integer
    Public Property Low As Integer
End Class

' serialization output formatted (pretty-printed with whitespace and indentation):
' {
'   "Date": "2019-08-01T00:00:00-07:00",
'   "TemperatureCelsius": 25,
'   "Summary": "Hot",
'   "DatesAvailable": [
'     "2019-08-01T00:00:00-07:00",
'     "2019-08-02T00:00:00-07:00"
'   ],
'   "TemperatureRanges": {
'     "Cold": {
'       "High": 20,
'       "Low": -10
'     },
'     "Hot": {
'       "High": 60,
'       "Low": 20
'     }
'   },
'   "SummaryWords": [
'     "Cool",
'     "Windy",
'     "Humid"
'   ]
' }

Pembuatan serial ke UTF-8

Ini 5-10% lebih cepat untuk diserialisasikan ke array byte UTF-8 daripada menggunakan metode berbasis string. Itu karena byte (sebagai UTF-8) tidak perlu dikonversi ke string (UTF-16).

Untuk membuat serial ke array byte UTF-8, panggil metode JsonSerializer.SerializeToUtf8Bytes:

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

Kelebihan Serialize yang membutuhkan Utf8JsonWriter juga tersedia.

Pembuatan serial ke JSON yang diformat

Untuk mencetak output JSON dengan cantik, atur JsonSerializerOptions.WriteIndented ke true:

using System.Text.Json;

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

    public class Program
    {
        public static void Main()
        {
            var weatherForecast = new WeatherForecast
            {
                Date = DateTime.Parse("2019-08-01"),
                TemperatureCelsius = 25,
                Summary = "Hot"
            };

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

            Console.WriteLine(jsonString);
        }
    }
}
// output:
//{
//  "Date": "2019-08-01T00:00:00-07:00",
//  "TemperatureCelsius": 25,
//  "Summary": "Hot"
//}

Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonString = JsonSerializer.Serialize(weatherForecast, options)

Tip

Jika Anda menggunakan JsonSerializerOptions berulang kali dengan opsi yang sama, jangan buat instans JsonSerializerOptions baru setiap kali menggunakannya. Gunakan kembali instans yang sama untuk setiap panggilan. Untuk informasi selengkapnya, lihat Menggunakan kembali instans JsonSerializerOptions.

Gunakan GitHub Copilot untuk membuat serialisasi ke JSON

Anda dapat menggunakan GitHub Copilot di IDE Anda untuk menghasilkan kode yang menggunakan untuk menserialisasikan System.Text.Json ke JSON.

Jika Anda menggunakan Visual Studio 2022 versi 17.8 atau yang lebih baru, Anda dapat mencoba GitHub Copilot berbasis AI di Visual Studio untuk menghasilkan kode yang digunakan System.Text.Json untuk membuat serialisasi ke JSON. Kirimkan pertanyaan Anda sebagai perintah di jendela obrolan Copilot, seperti dalam contoh berikut. Anda juga dapat mengirimkan perintah menggunakan obrolan sebaris di jendela editor itu sendiri.

Catatan

GitHub Copilot didukung oleh AI, sehingga kejutan dan kesalahan dimungkinkan. Pastikan untuk memverifikasi kode atau saran yang dihasilkan. Untuk informasi selengkapnya tentang penggunaan umum GitHub Copilot, dampak produk, pengawasan manusia, dan privasi, lihat Tanya Jawab Umum GitHub Copilot.

Teks berikut menunjukkan contoh perintah untuk Obrolan Salinan:

Hasilkan kode yang akan digunakan System.Text.Json untuk membuat serial objek ke string JSON. Objek berisi bidang berikut: FirstName (string), Lastname (string), Age (int). Berikan contoh output.

Anda dapat menyesuaikan perintah untuk menggunakan bidang objek yang sesuai dengan kebutuhan Anda.

Anda dapat menggunakan fitur obrolan, seperti perintah garis miring, referensi ke file, metode, atau kelas, dan utas, untuk mengatur niat dan mendapatkan jawaban yang lebih baik dengan konteks tercakup. Untuk kelas yang ada dalam proyek yang terbuka di IDE, Anda dapat meminta GitHub Copilot dengan /generate code to serialize #Classname in #Filename to JSON.

Output berikut menunjukkan contoh respons Obrolan Salinan:

Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string in C#:

using System;
using System.Text.Json;

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int Age { get; set; }
}

public class Program
{
    public static void Main()
    {
        var person = new Person
        {
            FirstName = "John",
            LastName = "Doe",
            Age = 30
        };

        string jsonString = JsonSerializer.Serialize(person);
        Console.WriteLine(jsonString);
    }
}

**Example Output**
{"FirstName":"John","LastName":"Doe","Age":30}

This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed to the console.

Saat Copilot mengembalikan blok kode, respons menyertakan opsi untuk menyalin kode, menyisipkan kode ke dalam file baru, atau mempratinjau output kode.

Catatan

Hasil Anda mungkin berbeda dari apa yang ditunjukkan dalam contoh respons. Model AI tidak deterministik, yang berarti bahwa mereka dapat mengembalikan respons yang berbeda ketika diajukan pertanyaan yang sama. Ini mungkin karena pembelajaran dan adaptasi tambahan dari waktu ke waktu, variasi bahasa, perubahan konteks, seperti riwayat obrolan Anda, dan banyak lagi.

Untuk informasi selengkapnya, lihat:

Bagikan melalui