Schreiben von .NET-Objekten in JSON (Serialisieren)

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 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)

Sie können KI auch verwenden, um Serialisierungscode für Sie zu generieren. Anweisungen finden Sie im Abschnitt "KI verwenden" 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 Typen 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 KI zum Serialisieren in JSON

Sie können KI-Tools wie GitHub Copilot verwenden, um Code zu generieren, der System.Text.Json zum Serialisieren nach JSON verwendet. Sie können die Eingabeaufforderung an Ihre Objektfelder und Serialisierungsanforderungen anpassen.

Hier ist eine Beispielaufforderung, die Sie zum Generieren von Serialisierungscode verwenden können:

I have a variable named weatherForecast of type WeatherForecast.
Serialize the variable using System.Text.Json and write the result directly to a file named "output.json" with the JSON indented for pretty formatting.
Ensure the code includes all necessary using directives and compiles without errors.

Überprüfen Sie die Vorschläge von Copilot, bevor Sie sie anwenden.

Weitere Informationen zu GitHub Copilot finden Sie in den häufig gestellten Fragen zu GitHub.

Siehe auch

GitHub Copilot in Visual Studio
GitHub Copilot in Visual Studio Code

Feedback

War diese Seite hilfreich?

Last updated on 2025-11-20