.NET-objektumok írása JSON-ként (szerializálás)

Cikk
10/26/2023

Ez a cikk bemutatja, hogyan szerializálhatja a System.Text.Json névteret a JavaScript Object Notation (JSON) névtérrel. Ha meglévő kódot Newtonsoft.Jsonportoz, olvassa el a Migrálás a következőre című témakörtSystem.Text.Json.

Ha JSON-t szeretne írni egy sztringbe vagy fájlba, hívja meg a metódust JsonSerializer.Serialize .

Az alábbi példa JSON-t hoz létre sztringként:

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

A JSON-kimenet alapértelmezés szerint minifikálva van (a szóköz, a behúzás és az új sor karakterei törlődnek).

Az alábbi példa szinkron kódot használ egy JSON-fájl létrehozásához:

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)

Az alábbi példa aszinkron kóddal hoz létre JSON-fájlt:

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)

Az előző példák típuskövetkeztetést használnak a szerializált típushoz. A túlterhelés egy Serialize() általános típusparamétert vesz igénybe:

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)

Szerializálási viselkedés

Alapértelmezés szerint minden nyilvános tulajdonság szerializálva van. Megadhatja a figyelmen kívül hagyandó tulajdonságokat. Magántagokat is felvehet.
Az alapértelmezett kódoló nem ASCII-karaktereket, HTML-érzékeny karaktereket az ASCII-tartományon belül, valamint az RFC 8259 JSON-specifikációnak megfelelő karaktereket tartalmaz.
Alapértelmezés szerint a JSON minifikálva van. Kinyomtathatja a JSON-t.
Alapértelmezés szerint a JSON-nevek burkolata megegyezik a .NET-névvel. Testre szabhatja a JSON-névházat.
Alapértelmezés szerint a rendszer körkörös hivatkozásokat észlel, és kivételeket ad ki. Megőrizheti a hivatkozásokat, és kezelheti a körkörös hivatkozásokat.
Alapértelmezés szerint a mezők figyelmen kívül lesznek hagyva. Mezőket is felvehet.

Ha közvetetten használ System.Text.Json egy ASP.NET Core-alkalmazásban, bizonyos alapértelmezett viselkedések eltérőek. További információ: A JsonSerializerOptions webes alapértelmezései.

A támogatott típusok a következők:

A JavaScript-primitívekre leképezhető .NET-primitívek, például numerikus típusok, sztringek és logikai értékek.
Felhasználó által definiált egyszerű régi CLR-objektumok (POCO-k).
Egydimenziós és szaggatott tömbök (T[][]).
Gyűjtemények és szótárak a következő névterekből:
További információ: Támogatott gyűjteménytípusok a következőben System.Text.Json: .

Egyéni konvertereket implementálhat további típusok kezelésére, vagy olyan funkciók biztosítására, amelyeket a beépített konverterek nem támogatnak.

Íme egy példa a gyűjteménytulajdonságokat és egy felhasználó által definiált típust tartalmazó osztály szerializálására:

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

Szerializálás UTF-8-ra

5-10%-kal gyorsabb szerializálni egy UTF-8 bájtos tömböt, mint a sztringalapú metódusokat. Ennek az az oka, hogy a bájtokat (UTF-8)nem kell sztringekké konvertálni (UTF-16).

Ha UTF-8 bájttömbbe szeretne szerializálni, hívja meg a metódust 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)

A Serialize túlterhelés, amely vesz egy Utf8JsonWriter is elérhető.

Szerializálás formázott JSON-ra

A JSON-kimenet szép nyomtatásához állítsa a JsonSerializerOptions.WriteIndented következőre 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)

Tipp.

Ha ugyanazokat a beállításokat használja JsonSerializerOptions többször is, ne hozzon létre új JsonSerializerOptions példányt minden alkalommal, amikor használja. Használja újra ugyanazt a példányt minden híváshoz. További információ: JsonSerializerOptions-példányok újrafelhasználása.

.NET-objektumok írása JSON-ként (szerializálás)

Szerializálási viselkedés

Szerializálás UTF-8-ra

Szerializálás formázott JSON-ra

Visszajelzés

További források