Jak zapisywać obiekty platformy .NET w formacie JSON (serializować)

Artykuł
10/26/2023

W tym artykule pokazano, jak używać System.Text.Json przestrzeni nazw do serializacji do notacji obiektów JavaScript (JSON). Jeśli przenosisz istniejący kod z Newtonsoft.Jsonprogramu , zobacz Jak przeprowadzić migrację do System.Text.Jsonprogramu .

Aby zapisać kod JSON w ciągu lub w pliku, wywołaj metodę JsonSerializer.Serialize .

Poniższy przykład tworzy kod JSON jako ciąg:

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

Dane wyjściowe JSON są domyślnie usuwane (białe znaki, wcięcia i znaki nowego wiersza).

W poniższym przykładzie użyto synchronicznego kodu do utworzenia pliku 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)

W poniższym przykładzie użyto kodu asynchronicznego do utworzenia pliku 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)

W poprzednich przykładach użyto wnioskowania typu dla typu, który jest serializowany. Przeciążenie Serialize() przyjmuje parametr typu ogólnego:

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)

Zachowanie serializacji

Domyślnie wszystkie właściwości publiczne są serializowane. Można określić właściwości do zignorowania. Możesz również uwzględnić prywatne elementy członkowskie.
Koder domyślny ucieka przed znakami innych niż ASCII, znakami wrażliwymi na kod HTML w zakresie ASCII i znakami, które muszą zostać uniknięci zgodnie ze specyfikacją JSON RFC 8259.
Domyślnie format JSON jest minyfikowany. Możesz dość wydrukować kod JSON.
Domyślnie wielkość liter nazw JSON jest zgodna z nazwami platformy .NET. Można dostosować wielkość liter nazw JSON.
Domyślnie odwołania cykliczne są wykrywane i zgłaszane wyjątki. Można zachować odwołania i obsłużyć odwołania cykliczne.
Domyślnie pola są ignorowane. Możesz uwzględnić pola.

Jeśli używasz System.Text.Json pośrednio w aplikacji ASP.NET Core, niektóre zachowania domyślne są inne. Aby uzyskać więcej informacji, zobacz Ustawienia domyślne sieci Web dla JsonSerializerOptions.

Obsługiwane typy obejmują:

Typy pierwotne platformy .NET mapujące na typy pierwotne języka JavaScript, takie jak typy liczbowe, ciągi i wartość logiczna.
Zdefiniowane przez użytkownika zwykłe stare obiekty CLR (POC).
Tablice jednowymiarowe i postrzępione (T[][]).
Kolekcje i słowniki z następujących przestrzeni nazw:
Aby uzyskać więcej informacji, zobacz Obsługiwane typy kolekcji w programie System.Text.Json.

Możesz zaimplementować niestandardowe konwertery do obsługi dodatkowych typów lub zapewnić funkcjonalność, która nie jest obsługiwana przez wbudowane konwertery.

Oto przykład pokazujący, jak klasa zawierająca właściwości kolekcji i typ zdefiniowany przez użytkownika są serializowane:

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

Serializowanie do formatu UTF-8

Szybkość serializacji do tablicy bajtów UTF-8 jest 5–10% szybsza niż w przypadku używania metod opartych na ciągach. Wynika to z faktu, że bajty (jako UTF-8) nie muszą być konwertowane na ciągi (UTF-16).

Aby serializować do tablicy bajtów UTF-8, wywołaj metodę 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)

Przeciążenie Serialize , które przyjmuje Utf8JsonWriter element , jest również dostępne.

Serializowanie do sformatowanego kodu JSON

Aby dość wydrukować dane wyjściowe JSON, ustaw wartość JsonSerializerOptions.WriteIndented :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)

Napiwek

Jeśli używasz JsonSerializerOptions wielokrotnie z tymi samymi opcjami, nie twórz nowego JsonSerializerOptions wystąpienia za każdym razem, gdy go używasz. Ponownie użyj tego samego wystąpienia dla każdego wywołania. Aby uzyskać więcej informacji, zobacz Ponowne używanie wystąpień JsonSerializerOptions.

Jak zapisywać obiekty platformy .NET w formacie JSON (serializować)

Zachowanie serializacji

Serializowanie do formatu UTF-8

Serializowanie do sformatowanego kodu JSON

Opinia

Dodatkowe zasoby