Skriva .NET-objekt som JSON (serialisera)
Den här artikeln visar hur du använder System.Text.Json namnområdet för att serialisera till JavaScript Object Notation (JSON). Om du porterar befintlig kod från Newtonsoft.Jsonläser du Så här migrerar du tillSystem.Text.Json .
Om du vill skriva JSON till en sträng eller till en fil anropar du JsonSerializer.Serialize metoden.
I följande exempel skapas JSON som en sträng:
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
JSON-utdata minimeras (blanksteg, indrag och nya radtecken tas bort) som standard.
I följande exempel används synkron kod för att skapa en JSON-fil:
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)
I följande exempel används asynkron kod för att skapa en JSON-fil:
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)
I föregående exempel används typinferens för den typ som serialiseras. En överlagring av Serialize() tar en allmän typparameter:
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)
Serialiseringsbeteende
- Som standard serialiseras alla offentliga egenskaper. Du kan ange egenskaper som ska ignoreras. Du kan också inkludera privata medlemmar.
- Standardkodaren undflyr icke-ASCII-tecken, HTML-känsliga tecken inom ASCII-intervallet och tecken som måste vara undantagna enligt RFC 8259 JSON-specifikationen.
- Som standard minimeras JSON. Du kan skriva ut JSON-filen på ett snyggt sätt.
- Som standard matchar höljet för JSON-namn .NET-namnen. Du kan anpassa JSON-namnhöljet.
- Som standard identifieras cirkelreferenser och undantag genereras. Du kan bevara referenser och hantera cirkelreferenser.
- Som standard ignoreras fälten . Du kan inkludera fält.
När du använder System.Text.Json indirekt i en ASP.NET Core-app skiljer sig vissa standardbeteenden åt. Mer information finns i Webbstandarder för JsonSerializerOptions.
Exempel på typer som stöds är:
.NET-primitiver som mappar till JavaScript-primitiver, till exempel numeriska typer, strängar och booleska.
Användardefinierade oformaterade gamla CLR-objekt (POCOs).
Endimensionella och ojämna matriser (
T[][]).Samlingar och ordlistor från följande namnområden:
- System.Collections
- System.Collections.Generic
- System.Collections.Immutable
- System.Collections.Concurrent
- System.Collections.Specialized
- System.Collections.ObjectModel
Mer information finns i Samlingstyper som stöds i System.Text.Json.
Du kan implementera anpassade konverterare för att hantera ytterligare typer eller för att tillhandahålla funktioner som inte stöds av de inbyggda konverterarna.
Här är ett exempel som visar hur en klass som innehåller samlingsegenskaper och en användardefinierad typ serialiseras:
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"
' ]
' }
Serialisera till UTF-8
Det går 5–10 % snabbare att serialisera till en UTF-8 byte-matris än att använda strängbaserade metoder. Det beror på att byte (som UTF-8) inte behöver konverteras till strängar (UTF-16).
Om du vill serialisera till en UTF-8 byte-matris anropar du JsonSerializer.SerializeToUtf8Bytes metoden:
byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);
Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
.WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)
En Serialize överlagring som tar en Utf8JsonWriter är också tillgänglig.
Serialisera till formaterad JSON
Om du vill skriva ut JSON-utdata på ett snyggt sätt anger du JsonSerializerOptions.WriteIndented till 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)
Dricks
Om du använder JsonSerializerOptions upprepade gånger med samma alternativ ska du inte skapa en ny JsonSerializerOptions instans varje gång du använder den. Återanvänd samma instans för varje anrop. Mer information finns i ÅteranvändA JsonSerializerOptions-instanser.
Feedback
Kommer snart: Under hela 2024 kommer vi att fasa ut GitHub-problem som feedbackmekanism för innehåll och ersätta det med ett nytt feedbacksystem. Mer information finns i: https://aka.ms/ContentUserFeedback.
Skicka och visa feedback för