Jak psát objekty .NET jako JSON (serializovat)

Článek
09/07/2024

Tento článek ukazuje, jak použít System.Text.Json obor názvů k serializaci do JavaScript Object Notation (JSON). Pokud portujete existující kód z Newtonsoft.Json, přečtěte si, jak migrovat na System.Text.Json.

Tip

Pomoc s AI můžete použít k serializaci do formátu JSON pomocí GitHub Copilotu.

Pokud chcete napsat JSON do řetězce nebo do souboru, zavolejte metodu JsonSerializer.Serialize .

Příklady serializace

Následující příklad vytvoří JSON jako řetězec:

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

Ve výchozím nastavení je výstup JSON minifikovaný (prázdné znaky, odsazení a znaky nového řádku se odeberou).

Následující příklad používá synchronní kód k vytvoření souboru 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)

Následující příklad používá asynchronní kód k vytvoření souboru 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)

Předchozí příklady používají odvození typu pro typ, který je serializován. Přetížení Serialize() přebírá parametr obecného typu:

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)

K vygenerování kódu serializace můžete použít také GitHub Copilot. Pokyny najdete v části Použití githubového copilotu v tomto článku.

Chování serializace

Ve výchozím nastavení jsou všechny veřejné vlastnosti serializovány. Můžete zadat vlastnosti, které chcete ignorovat. Můžete také zahrnout soukromé členy.
Výchozí kodér umiskne znaky jiné než ASCII, znaky citlivé na HTML v rozsahu ASCII a znaky, které musí být uchycené podle specifikace RFC 8259 JSON.
Ve výchozím nastavení je JSON minifikovaný. Json můžete poměrně vytisknout.
Ve výchozím nastavení se velikost písmen názvů JSON shoduje s názvy .NET. Můžete přizpůsobit velikost názvu JSON.
Ve výchozím nastavení jsou cyklické odkazy zjištěny a vyvolány výjimky. Můžete zachovat odkazy a zpracovat cyklický odkaz.
Ve výchozím nastavení se pole ignorují. Můžete zahrnout pole.

Když v aplikaci ASP.NET Core použijete System.Text.Json nepřímo, liší se některé výchozí chování. Další informace najdete v tématu Výchozí nastavení webu pro JsonSerializerOptions.

Mezi podporované typy patří:

Primitiva .NET, která se mapují na primitiva JavaScriptu, jako jsou číselné typy, řetězce a logická hodnota.
Uživatelem definované prosté staré objekty CLR (POCOs)
Jednorozměrná a žloutlá pole (T[][]).
Kolekce a slovníky z následujících oborů názvů:
Další informace naleznete v tématu Podporované typy kolekcí v System.Text.Json.

Můžete implementovat vlastní převaděče pro zpracování dalších typů nebo poskytování funkcí, které nejsou podporovány integrovanými převaděči.

Tady je příklad znázorňující, jak se serializuje třída, která obsahuje vlastnosti kolekce a typ definovaný uživatelem:

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"
'   ]
' }

Serializace do UTF-8

Serializace na bajtové pole UTF-8 je 5 až 10 % rychlejší než použití metod založených na řetězcích. Je to proto, že bajty (jako UTF-8) nemusí být převedeny na řetězce (UTF-16).

Chcete-li serializovat na bajtové pole UTF-8, zavolejte metodu 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)

Přetížení Serialize , které přebírá Utf8JsonWriter také je k dispozici.

Serializace do formátovaného FORMÁTU JSON

Pokud chcete výstup JSON poměrně vytisknout, nastavte JsonSerializerOptions.WriteIndented na 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)

Od verze .NET 9 můžete také přizpůsobit znak odsazení a velikost pomocí IndentCharacter a IndentSize.

Tip

Pokud používáte JsonSerializerOptions opakovaně se stejnými možnostmi, nevytvávejte při každém použití novou JsonSerializerOptions instanci. Znovu použijte stejnou instanci pro každé volání. Další informace najdete v tématu Opětovné použití instancí JsonSerializerOptions.

Serializace do formátu JSON pomocí GitHub Copilotu

Pomocí GitHub Copilotu v integrovaném vývojovém prostředí (IDE) můžete vygenerovat kód, který se používá System.Text.Json k serializaci do formátu JSON.

Pokud používáte Visual Studio 2022 verze 17.8 nebo novější, můžete vyzkoušet GitHub Copilot řízený pomocí AI v sadě Visual Studio a vygenerovat kód, který se používá System.Text.Json k serializaci do FORMÁTU JSON. Odešlete otázku jako výzvu v okně chatu Copilot, jak je znázorněno v následujícím příkladu. Můžete také odesílat výzvy pomocí vloženého chatu v samotném okně editoru.

Poznámka:

GitHub Copilot využívá technologii AI, takže jsou možná překvapení a chyby. Nezapomeňte ověřit vygenerovaný kód nebo návrhy. Další informace o obecném použití GitHub Copilotu, dopadu produktu, lidského dohledu a ochrany osobních údajů najdete v nejčastějších dotazech ke Kopírování GitHubu.

Následující text ukazuje příklad výzvy ke kopírování chatu:

Vygenerujte kód, který se použije System.Text.Json k serializaci objektu do řetězce JSON. Objekt obsahuje následující pole: FirstName (string), Lastname (string), Age (int). Zadejte příklad výstupu.

Výzvu můžete přizpůsobit tak, aby používala pole objektů, která vyhovují vašim požadavkům.

Pomocí funkcí chatu, jako jsou příkazy lomítka, odkazy na soubory, metody nebo třídy a vlákna, můžete nastavit záměr a získat lepší odpovědi s vymezeným kontextem. Pro existující třídu v projektu, který je otevřen v integrovaném vývojovém prostředí, můžete vyzvat GitHub Copilot s /generate code to serialize #Classname in #Filename to JSON.

Následující výstup ukazuje příklad odpovědi copilot chatu:

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.

Když Copilot vrátí blok kódu, odpověď obsahuje možnosti pro zkopírování kódu, vložení kódu do nového souboru nebo náhled výstupu kódu.

Poznámka:

Výsledky se můžou lišit od toho, co se zobrazuje v ukázkových odpovědích. Modely AI nejsou deterministické, což znamená, že při kladení stejné otázky můžou vrátit různé odpovědi. Důvodem může být další učení a přizpůsobení v průběhu času, jazykové variace, změny v kontextu, například historie chatu a další.

Další informace naleznete v tématu:

Sdílet prostřednictvím