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

Artykuł
12/21/2024

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 .

Napiwek

Za pomocą pomocy sztucznej inteligencji można serializować dane JSON za pomocą narzędzia GitHub Copilot.

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

Przykłady serializacji

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)

Możesz również użyć narzędzia GitHub Copilot, aby wygenerować kod serializacji. Aby uzyskać instrukcje, zobacz sekcję Use GitHub Copilot (Korzystanie z narzędzia GitHub Copilot ) w tym artykule.

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 w 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)

Począwszy od platformy .NET 9, można również dostosować znak i rozmiar wcięcia przy użyciu narzędzi IndentCharacter i IndentSize.

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.

Używanie narzędzia GitHub Copilot do serializacji do formatu JSON

Możesz użyć narzędzia GitHub Copilot w środowisku IDE, aby wygenerować kod używany System.Text.Json do serializacji do formatu JSON. Możesz dostosować monit, aby używać pól obiektów odpowiadających twoim wymaganiom.

Poniższy tekst przedstawia przykładowy monit dotyczący czatu copilot:

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.

Narzędzie GitHub Copilot jest obsługiwane przez sztuczną inteligencję, więc możliwe są niespodzianki i błędy. Aby uzyskać więcej informacji, zobacz Copilot FAQs.

Dowiedz się więcej o GitHub Copilot w programie Visual Studio i GitHub Copilot w programie VS Code.

Udostępnij za pośrednictwem