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

2025-06-28

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

Aby serializować dane w formacie JSON, możesz użyć pomocy dotyczącej sztucznej inteligencji.

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ą zminimalizowane (białe znaki, wcięcia i znaki nowego wiersza są usuwane) domyślnie.

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ć sztucznej inteligencji, aby wygenerować kod serializacji. Aby uzyskać instrukcje, zobacz sekcję Korzystanie ze sztucznej inteligencji 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ć prywatnych członków.
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 ładnie sformatować kod JSON.
Domyślnie wielkość liter nazw JSON odpowiada nazwom w .NET. Można dostosować wielkość liter nazw JSON.
Domyślnie odwołania cykliczne są wykrywane i wyjątki są zgłaszane. 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 prymitywne .NET, które mapują do typów prymitywnych JavaScript, takie jak typy liczbowe, łańcuchy i typ logiczny.
Określone przez użytkownika zwykłe stare obiekty CLR (POCO).
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, jest również dostępne.

Serializowanie do sformatowanego kodu JSON

Aby pięknie sformatować dane wyjściowe JSON, ustaw 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)

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 wielokrotnie używasz JsonSerializerOptions z tymi samymi opcjami, nie twórz za każdym razem nowego wystąpienia JsonSerializerOptions. 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 sztucznej inteligencji do serializacji do formatu JSON

Możesz użyć narzędzi sztucznej inteligencji, takich jak GitHub Copilot, aby wygenerować kod, który używa 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.

Udostępnij za pośrednictwem