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

Artykuł
09/07/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 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)

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.

Jeśli używasz programu Visual Studio 2022 w wersji 17.8 lub nowszej, możesz wypróbować narzędzie GitHub Copilot oparte na sztucznej inteligencji w programie Visual Studio , aby wygenerować kod używany System.Text.Json do serializacji do formatu JSON. Prześlij swoje pytanie jako monit w oknie czatu Copilot, jak w poniższym przykładzie. Możesz również przesyłać monity przy użyciu wbudowanego czatu w samym oknie edytora.

Uwaga

Narzędzie GitHub Copilot jest obsługiwane przez sztuczną inteligencję, więc możliwe są niespodzianki i błędy. Upewnij się, że zweryfikowano wygenerowany kod lub sugestie. Aby uzyskać więcej informacji na temat ogólnego użycia narzędzia GitHub Copilot, wpływu produktu, nadzoru ludzkiego i prywatności, zobacz GitHub Copilot — często zadawane pytania.

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

Generowanie kodu używanego do System.Text.Json serializacji obiektu do ciągu JSON. Obiekt zawiera następujące pola: FirstName (ciąg), Lastname (ciąg), Age (int). Podaj przykładowe dane wyjściowe.

Możesz dostosować monit, aby używać pól obiektów odpowiadających twoim wymaganiom.

Możesz użyć funkcji czatu, takich jak polecenia ukośnika, odwołania do plików, metod lub klas i wątków, aby ustawić intencję i uzyskać lepsze odpowiedzi z kontekstem o określonym zakresie. W przypadku istniejącej klasy w projekcie otwartym w środowisku IDE możesz wyświetlić monit GitHub Copilot za pomocą polecenia /generate code to serialize #Classname in #Filename to JSON.

W poniższych danych wyjściowych przedstawiono przykładową odpowiedź czatu copilot:

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.

Gdy copilot zwraca blok kodu, odpowiedź zawiera opcje kopiowania kodu, wstawiania kodu do nowego pliku lub podglądu danych wyjściowych kodu.

Uwaga

Wyniki mogą się różnić od przedstawionych w przykładowych odpowiedziach. Modele sztucznej inteligencji są niedeterministyczne, co oznacza, że mogą zwracać różne odpowiedzi po zadawaniu tego samego pytania. Może to być spowodowane dodatkowym uczeniem się i adaptacją w czasie, odmianą języka, zmianami w kontekście, takimi jak historia czatów i nie tylko.

Aby uzyskać więcej informacji, zobacz:

Udostępnij za pośrednictwem