Jak zapisywać obiekty platformy .NET w formacie JSON (serializować)
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.Json
programu , zobacz Jak przeprowadzić migrację do System.Text.Json
programu .
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:
- System.Collections
- System.Collections.Generic
- System.Collections.Immutable
- System.Collections.Concurrent
- System.Collections.Specialized
- System.Collections.ObjectModel
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.
Opinia
https://aka.ms/ContentUserFeedback.
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź:Prześlij i wyświetl opinię dla