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

2025-06-28

Tento článek ukazuje, jak použít jmenný prostor System.Text.Json 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.

Návod

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

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řijímá 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)

AI můžete také použít k vygenerování kódu serializace za vás. Pokyny najdete v části Použití AI 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í enkodér nahrazuje znaky jiné než ASCII, znaky citlivé na HTML v rámci ASCII-rozsahu a znaky, které musí být escapovány podle specifikace RFC 8259 JSON.
Ve výchozím nastavení je JSON minifikovaný. JSON můžete hezky formátovat.
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í dochází k detekci cyklických odkazů a vyvolání výjimek. Můžete zachovat odkazy a zpracovat cyklické odkazy.
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á odpovídají primitivům JavaScriptu, jako jsou číselné typy, řetězce a logické hodnoty.
Uživatelem definované prosté staré objekty CLR (POCOs)
Jednorozměrná a zubatá pole (T[][]).
Kolekce a slovníky z následujících oborů názvů:
Další informace naleznete v sekci Podporované typy 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, je také k dispozici.

Serializace do formátovaného FORMÁTU JSON

Pokud chcete výstup JSON hezky formátovat, 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.

Návod

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.

Použití AI k serializaci do FORMÁTU JSON

Pomocí nástrojů AI, jako je GitHub Copilot, můžete generovat kód, který používá System.Text.Json k serializaci do JSON. Výzvu můžete přizpůsobit tak, aby používala pole objektů, která vyhovují vašim požadavkům.

Následující text ukazuje příklad ukázkového příkazu pro Copilot Chat:

Generate code to use System.Text.Json to serialize an object to a JSON string.
The object contains the following fields: FirstName (string), Lastname (string), Age (int).
Provide example output.

GitHub Copilot využívá technologii AI, takže jsou možná překvapení a chyby. Další informace najdete v nejčastějších dotazech ke copilotu.

Sdílet prostřednictvím