Schreiben von .NET-Objekten in JSON (Serialisieren)

Artikel
10/15/2024

Dieser Artikel veranschaulicht, wie Sie mithilfe des System.Text.Json-Namespace Daten in das JSON-Format (JavaScript Object Notation) serialisieren. Wenn Sie vorhandenen Code aus Newtonsoft.Json portieren, finden Sie weitere Informationen unter Migrieren zu System.Text.Json.

Tipp

Sie können KI-Unterstützung verwenden, um mit GitHub Copilot zu JSON zu serialisieren.

Um JSON in eine Zeichenfolge oder eine Datei zu schreiben, rufen Sie die JsonSerializer.Serialize-Methode auf.

Serialisierungsbeispiele

Im folgenden Beispiel wird JSON als Zeichenfolge erstellt:

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

Die JSON-Ausgabe ist standardmäßig minified (Leerzeichen, Einrückungen und Zeilenumbrüche werden entfernt).

Im folgenden Beispiel wird synchroner Code verwendet, um eine JSON-Datei zu erstellen:

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)

Im folgenden Beispiel wird asynchroner Code verwendet, um eine JSON-Datei zu erstellen:

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)

In den vorangehenden Beispielen wird Typrückschluss für den zu serialisierenden Typ verwendet. Eine Überladung von Serialize() akzeptiert einen generischen 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)

Mit GitHub Copilot können Sie auch Serialisierungscode generieren. Anweisungen finden Sie im Abschnitt GitHub Copilot in diesem Artikel.

Serialisierungsverhalten

Standardmäßig werden alle öffentlichen Eigenschaften serialisiert. Sie können zu ignorierende Eigenschaften angeben. Sie können auch private Mitglieder einschließen.
Der Standardencoder escapet Nicht-ASCII-Zeichen, HTML-abhängige Zeichen innerhalb des ASCII-Bereichs und Zeichen, die gemäß JSON-Spezifikation RFC 8259 escapet werden müssen.
JSON wird standardmäßig verkleinert. Sie können den JSON-Code übersichtlich formatieren.
Standardmäßig entspricht die Groß-/Kleinschreibung von JSON-Namen der von .NET-Namen. Sie können die Groß-/Kleinschreibung von JSON-Namen anpassen.
Zirkelbezüge werden standardmäßig erkannt und entsprechende Ausnahmen ausgelöst. Sie können Verweise beibehalten und Zirkelbezüge behandeln.
Felder werden standardmäßig ignoriert. Sie können Felder einschließen.

Wenn Sie System.Text.Json indirekt in einer ASP.NET Core-App verwenden, unterscheiden sich einige Standardverhaltensweisen. Weitere Informationen finden Sie unter Webstandardwerte für JsonSerializerOptions.

Unter anderem unterstützte Typen:

.NET-Primitive, die JavaScript-Primitiven entsprechen, z. B. numerische Typen, Zeichenfolgen und boolesche Werte.
benutzerdefinierte Plain Old CLR Objects (POCOs)
Eindimensionale und Jagged Arrays (T[][]).
Sammlungen und Wörterbücher aus den folgenden Namespaces:
Weitere Informationen finden Sie unter Unterstützte Sammlungstypen in System.Text.Json.

Sie können benutzerdefinierte Konverter implementieren, um zusätzliche Typen zu verarbeiten oder Funktionen bereitzustellen, die von den integrierten Konvertern nicht unterstützt werden.

Im folgenden Beispiel wird gezeigt, wie eine Klasse serialisiert wird, die Sammlungseigenschaften und einen benutzerdefinierten Typ enthält:

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"
'   ]
' }

Serialisieren in UTF-8

Es ist 5-10 % schneller, um in ein UTF-8-Byte-Array zu serialisieren, als die zeichenfolgenbasierten Methoden zu verwenden. Das liegt daran, dass die Bytes (als UTF-8) nicht in Zeichenfolgen (UTF-16) konvertiert werden müssen.

Um in ein UTF-8-Bytearray zu serialisieren, rufen Sie die JsonSerializer.SerializeToUtf8Bytes-Methode auf:

byte[] jsonUtf8Bytes =JsonSerializer.SerializeToUtf8Bytes(weatherForecast);

Dim jsonUtf8Bytes As Byte()
Dim options As JsonSerializerOptions = New JsonSerializerOptions With {
    .WriteIndented = True
}
jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes(weatherForecast1, options)

Eine Serialize-Überladung, die einen Utf8JsonWriter akzeptiert, ist ebenfalls verfügbar.

Serialisieren in formatierten JSON-Code

Um die JSON-Ausgabe übersichtlich zu formatieren, legen Sie JsonSerializerOptions.WriteIndented auf true fest:

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)

Ab .NET 9 können Sie auch das Einrückungszeichen und die Größe mit IndentCharacter und IndentSize anpassen.

Tipp

Wenn Sie JsonSerializerOptions wiederholt mit den gleichen Optionen verwenden, sollten Sie nicht bei jeder Verwendung eine neue JsonSerializerOptions-Instanz erstellen. Verwenden Sie für jeden Aufruf dieselbe Instanz. Weitere Informationen finden Sie unter Wiederverwenden von JsonSerializerOptions-Instanzen.

Verwenden von GitHub Copilot zum Serialisieren zu JSON

Sie können GitHub Copilot in Ihrer IDE verwenden, um Code zu generieren, der System.Text.Json verwendet, um zu JSON zu serialisieren.

Wenn Sie Visual Studio 2022, Version 17.8 oder höher verwenden, können Sie GitHub Copilot in Visual Studio mit KI-Unterstützung ausprobieren, um Code zu generieren, der für die Serialisierung zu JSON System.Text.Json verwendet. Reichen Sie im Chat-Fenster von Copilot Ihre Frage als Eingabeaufforderung ein. Sehen Sie sich hierzu das folgende Beispiel an. Sie können Eingabeaufforderungen auch über den Inline-Chat im Editorfenster senden.

Hinweis

GitHub Copilot wird von KI unterstützt. Daher sind Überraschungen und Fehler möglich. Überprüfen Sie jeden generierten Code oder alle Vorschläge. Weitere Informationen zur allgemeinen Verwendung von GitHub Copilot, zu den Auswirkungen des Produkts, zur menschlichen Aufsicht und zum Datenschutz finden Sie unter Häufig gestellte Fragen zu GitHub Copilot.

Der folgende Text zeigt eine Beispielaufforderung für Copilot Chat:

Generieren von Code, um System.Text.Json zum Serialisieren eines Objekts in eine JSON-Zeichenfolge zu verwenden. Das Objekt enthält die folgenden Felder: FirstName (string), Lastname (string), Age (int). Ein Beispiel für eine Ausgabe bereitstellen.

Sie können die Eingabeaufforderung anpassen, um Objektfelder zu verwenden, die Ihren Anforderungen entsprechen.

Sie können Chat-Funktionen wie Slash-Befehle, Verweise auf Dateien, Methoden oder Klassen sowie Threads verwenden, um eine Absicht festzulegen und bessere Antworten mit bereichsbezogenem Kontext zu erhalten. Für eine Klasse, die in einem in der IDE geöffneten Projekt vorhanden ist, können Sie an GitHub Copilot die Aufforderung /generate code to serialize #Classname in #Filename to JSON senden.

Die folgende Ausgabe zeigt ein Beispiel für eine Copilot Chat-Antwort:

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.

Wenn Copilot einen Codeblock zurückgibt, dann werden in der Antwort Optionen zum Kopieren des Codes, zum Einfügen des Codes in eine neue Datei oder zum Anzeigen einer Vorschau des Codes aufgelistet.

Hinweis

Die Ergebnisse können möglicherweise von den in diesen Beispielantworten gezeigten Ergebnissen abweichen. KI-Modelle sind nicht deterministisch. Das bedeutet, dass sie auf die gleiche Frage verschiedene Antworten zurückgeben können. Dies kann auf zusätzliche Lernaktivitäten und Anpassung im Laufe der Zeit, Sprachvariation, Änderungen im Kontext, wie z. B. Ihren Chatverlauf und viele weiter Faktoren zurückzuführen sein.

Weitere Informationen finden Sie unter:

Freigeben über