C# JSON mit System.Text.Json lesen & schreiben – einfach erklärt

APIs, Konfigurationsdateien, Datenaustausch zwischen Systemen - überall begegnet dir JSON (JavaScript Object Notation). Spätestens wenn eine REST-API dir Daten als JSON-String zurückgibt und du damit in C# arbeiten sollst, führt kein Weg daran vorbei. Hier lernst du, wie du mit `System.Text.Json` JSON in C# liest, Objekte in JSON umwandelst und typische Stolpersteine vermeidest. Am Ende steht ein lauffähiges Programm, das beides kann: lesen und schreiben.

Voraussetzungen: Was brauchst du?

Du brauchst grundlegende C#-Kenntnisse: Klassen, Properties und einfache Datentypen. Falls du noch unsicher bist, wie du überhaupt Dateien in C# einliest, wirf vorher einen Blick in unseren Artikel C# Datei lesen schreiben: StreamReader & StreamWriter.

An Software reicht:

• .NET SDK (ab Version 6, aktuelle Version unter https://dotnet.microsoft.com/download)

• Ein Editor wie Visual Studio, VS Code oder Rider

• Ein Konsolenprojekt: `dotnet new console -o JsonDemo`

Merke: `System.Text.Json` ist ab .NET Core 3.0 automatisch dabei - kein NuGet-Paket nötig. Nur im alten .NET Framework 4.x müsstest du es per NuGet nachinstallieren.

Die offizielle Dokumentation findest du auf Microsoft Learn.

Was ist System.Text.Json?

System.Text.Json ist die von Microsoft mitgelieferte JSON-Bibliothek für .NET. Sie wandelt C#-Objekte in JSON-Text um und umgekehrt - schnell, speichereffizient und ohne externe Abhängigkeiten.

Dabei gibt es zwei Richtungen:

Stell dir Serialisieren wie Kofferpacken vor: Du verstaust deine Kleidung (Objekte) in ein standardisiertes Format (JSON), das jeder Transporteur versteht. Deserialisieren ist das Auspacken am Zielort.

Schritt 1: Eine Klasse als Datenmodell erstellen

In C# bildest du JSON-Strukturen üblicherweise mit einer Klasse ab, deren Properties zu den JSON-Schlüsseln passen. Für dieses Beispiel nutzen wir eine einfache Klasse - Records gehen übrigens genauso:

public class Person
{
  public int Id { get; set; }
  public string Name { get; set; }
  public string Email { get; set; }
  public List<string> Kenntnisse { get; set; }
}

Dazu passend ein JSON-String, wie ihn eine API liefern könnte:

{
  "id": 1,
  "name": "Anna Schmidt",
  "email": "anna@example.com",
  "kenntnisse": ["C#", "SQL", "JSON"]
}

Wichtig: Die Property-Namen in C# sollten den Schlüsseln im JSON entsprechen - zumindest fast, dazu später mehr.

Schritt 2: Wie liest du JSON? - Deserialisieren

Kernantwort: JSON liest du in C# mit `JsonSerializer.Deserialize<T>(json)`. Daraus entsteht ein typisiertes Objekt vom Typ `T`.

Beim Deserialisieren übergibst du den JSON-String und den Zieldatentyp:

using System.Text.Json;

string json = """
  {
    "id": 1,
    "name": "Anna Schmidt",
    "email": "anna@example.com",
    "kenntnisse": ["C#", "SQL", "JSON"]
  }
  """;

Person? person = JsonSerializer.Deserialize<Person>(json);

if (person is not null)
{
  Console.WriteLine(person.Name);           // Ausgabe: Anna Schmidt
  Console.WriteLine(person.Kenntnisse[0]);  // Ausgabe: C#
}

Der Rückgabetyp ist `Person?` - also nullable. Warum? Weil `Deserialize` `null` zurückgeben kann, wenn der JSON-String wortwörtlich `null` enthält. Prüfe das Ergebnis also ab, bevor du darauf zugreifst. Mehr dazu findest du in unserem Artikel zu Nullable-Typen in C#.

Merke: `Deserialize` liefert bei JSON-Inhalt `null` ein `null` zurück. Ein leerer String wirft stattdessen eine `ArgumentException` - fang also nie beides auf dieselbe Art ab.

Schritt 3: Wie schreibst du JSON? - Serialisieren

Kernantwort: JSON schreibst du in C# mit `JsonSerializer.Serialize(objekt)`. Daraus entsteht ein JSON-String.

Der umgekehrte Weg geht mit `Serialize`. Mit Optionen sorgst du dafür, dass das Ergebnis lesbar formatiert ist:

using System.Text.Json;

var person = new Person
{
  Id = 2,
  Name = "Max Weber",
  Email = "max@example.com",
  Kenntnisse = new List<string> { "C#", "Docker" }
};

var optionen = new JsonSerializerOptions
{
  WriteIndented = true  // erzeugt Zeilenumbrueche und Einrueckung
};

string json = JsonSerializer.Serialize(person, optionen);
Console.WriteLine(json);

Ohne `WriteIndented = true` bekommst du den JSON-String als eine einzige lange Zeile - kompakt, aber für Menschen schwer lesbar. Für APIs ist die kompakte Form durchaus üblich, zum Debuggen empfiehlt sich die eingerückte Variante.

Schritt 4: Property-Namen anpassen mit JsonPropertyName

Ein Klassiker im echten Projektalltag: Die API liefert englische Schlüssel wie `"first_name"`, deine C#-Klasse folgt aber den Microsoft-Namenskonventionen. Für diesen Fall gibt es das `JsonPropertyName`-Attribut:

using System.Text.Json.Serialization;

public class Person
{
  [JsonPropertyName("id")]
  public int Id { get; set; }

  [JsonPropertyName("first_name")]
  public string Name { get; set; }

  public string Email { get; set; }
}

Damit wird beim Serialisieren `Name` als `"first_name"` ausgegeben - und beim Deserialisieren entsprechend eingelesen. Wie Attribute generell funktionieren, haben wir in einem eigenen Artikel erklärt.

Schritt 5: JSON aus einer Datei lesen und in eine Datei schreiben

In echten Anwendungen liegt JSON meist in Dateien. Zum Lesen und Schreiben kombinierst du `JsonSerializer` einfach mit der `File`-Klasse:

using System.Text.Json;

// JSON aus Datei lesen (deserialisieren)
string dateiInhalt = await File.ReadAllTextAsync("personen.json");
List<Person>? personen = JsonSerializer.Deserialize<List<Person>>(dateiInhalt);

// Liste als JSON in Datei schreiben (serialisieren)
var optionen = new JsonSerializerOptions { WriteIndented = true };
string json = JsonSerializer.Serialize(personen, optionen);
await File.WriteAllTextAsync("personen_backup.json", json);

Beachte: Eine JSON-Datei kann auch ein ganzes Array enthalten - dann deserialisierst du direkt in eine `List<Person>`.

Vollständiges Beispiel: Alles zusammengeführt

Hier das komplette Programm zum Nachbauen - eine Datei `Program.cs`, lauffähig mit `dotnet run`:

using System.Text.Json;
using System.Text.Json.Serialization;

public class Person
{
  [JsonPropertyName("id")]
  public int Id { get; set; }

  [JsonPropertyName("first_name")]
  public string Name { get; set; }

  public string Email { get; set; }

  public List<string> Kenntnisse { get; set; }
}

public class Program
{
  public static async Task Main()
  {
    // 1. Deserialisieren: JSON-String -> Objekt
    string json = """
      {
        "id": 1,
        "first_name": "Anna Schmidt",
        "email": "anna@example.com",
        "kenntnisse": ["C#", "SQL", "JSON"]
      }
      """;

    Person? person = JsonSerializer.Deserialize<Person>(json);

    if (person is null)
    {
      Console.WriteLine("Deserialisierung fehlgeschlagen.");
      return;
    }

    Console.WriteLine($"Geladen: {person.Name} ({person.Email})");

    // 2. Serialisieren: Objekt -> JSON-String
    var optionen = new JsonSerializerOptions { WriteIndented = true };
    string ausgabe = JsonSerializer.Serialize(person, optionen);
    Console.WriteLine(ausgabe);

    // 3. In Datei schreiben
    await File.WriteAllTextAsync("person.json", ausgabe);
    Console.WriteLine("Datei gespeichert.");
  }
}

Häufige Probleme & Lösungen

Die folgenden drei Fehler begegnen fast jedem, der zum ersten Mal mit C# JSON verarbeitet - und alle drei sind schnell behoben.

Problem 1: Properties bleiben plötzlich leer

Der JSON-String enthält `"id"`, deine Klasse erwartet aber standardmäßig exakt `Id` - die Zuordnung ist case-sensitiv. Ergebnis: Die Property bekommt den Standardwert `0` und du wunderst dich.

Lösung: Aktiviere case-insensitives Verhalten:

var optionen = new JsonSerializerOptions
{
  PropertyNameCaseInsensitive = true
};

Person? person = JsonSerializer.Deserialize<Person>(json, optionen);

Problem 2: JsonException wegen fehlerhaftem JSON

Fehlt eine schließende Klammer oder ein Anführungszeichen, wirft `Deserialize` eine `JsonException`. Baue eine Prüfung ein - gerade bei Daten aus dem Internet solltest du niemals blind vertrauen:

try
{
  Person? person = JsonSerializer.Deserialize<Person>(json);
}
catch (JsonException ex)
{
  Console.WriteLine($"Ungueltiges JSON: {ex.Message}");
}

Merke: Fehlt ein Schlüssel im JSON, wirft C# keinen Fehler - die Property bekommt einfach ihren Standardwert (`0`, `null` etc.). Prüfe wichtige Werte nach dem Deserialisieren selbst.

Problem 3: Performance-Falle bei JsonSerializerOptions

Wer bei jedem Aufruf `new JsonSerializerOptions()` erzeugt, verschenkt Leistung: Jede Instanz baut sich ihren eigenen Metadaten-Cache auf. Microsoft empfiehlt, eine Options-Instanz einmal anzulegen und wiederzuverwenden - für Web-Szenarien gibt es mit `JsonSerializerOptions.Web` sogar eine fertige Instanz. Details dazu liefert die offizielle Dokumentation zu Konfigurationsoptionen. Für Lernprojekte ist das noch irrelevant, im Berufsumfeld aber ein Qualitätskriterium.

FAQ

Was ist der Unterschied zwischen System.Text.Json und Newtonsoft.Json?

`Newtonsoft.Json` (Json.NET) war jahrelang der Standard und ist flexibler. `System.Text.Json` ist seit .NET Core 3.0 eingebaut, schneller und wird von Microsoft aktiv weiterentwickelt. Für neue Projekte ist `System.Text.Json` die erste Wahl - viele Legacy-Projekte laufen aber noch mit Newtonsoft.

Wie lese ich JSON ohne eine passende Klasse?

Mit `JsonDocument` und `JsonElement` kannst du JSON dynamisch durchlaufen, ähnlich wie ein Wörterbuch. Für strukturierte Daten sind typisierte Klassen aber wartbarer und typo-sicher.

using JsonDocument doc = JsonDocument.Parse(json);
string? name = doc.RootElement.GetProperty("first_name").GetString();

Funktioniert das auch mit verschachtelten Objekten?

Ja. Definiere einfach Klassen, deren Properties wieder Klassen sind. `System.Text.Json` löst beliebig tiefe Strukturen automatisch auf - solange die Typen matchen.

Kann ich JSON asynchron aus einem Stream lesen?

Ja, mit `JsonSerializer.DeserializeAsync<T>(stream)`. Das ist bei großen Dateien oder HTTP-Antworten speicherschonender, als erst den kompletten String einzulesen.

Fazit

JSON lesen und schreiben gehört für Azubis, Studierende und Berufseinsteiger zum Grundhandwerk - egal ob API-Anbindung, Konfigurationsdateien oder Datenaustausch. Mit `Serialize` und `Deserialize` hast du die zwei Kernmethoden von `System.Text.Json` kennengelernt, mit `JsonPropertyName` und `JsonSerializerOptions` die wichtigsten Stellschrauben. Die komplette API-Referenz findest du auf Microsoft Learn.

Wenn du bei C#, JSON oder anderen Prüfungsthemen Unterstützung brauchst: Wir von study-it.education unterstützen dich mit individueller Nachhilfe - auf dein Tempo und deine Prüfungen zugeschnitten. Schau vorbei und vereinbare deine erste Stunde.