Liersch.Json – JSON-Unterstützung für .NET – Steffen Liersch

Liersch.Json ist eine kompakte .NET-Bibliothek zum Parsen und Erzeugen von JSON-Dokumenten. Die Implementierung basiert auf C# 3.0 und ist für folgende .NET-Plattformen geeignet:

ab .NET Framework 2.0
ab .NET Core 1.0
ab .NET Standard 1.0
Mono
.NET Micro Framework 4.4

Die kompilierte Bibliothek hat eine Größe von lediglich ≈25 kB. Alle nennenswerten Bibliotheksänderungen werden in der Datei CHANGELOG.md protokolliert.

Verwendung der Bibliothek

Liersch.Json ist auf NuGet verfügbar und kann über diesen Wege sehr komfortabel in neue oder bestehende Projekte integriert werden. Für ältere Projekte (vor .NET Framework 4.0) muss die Bibliothek manuell kompiliert und integriert werden. Mit Hilfe des Compilersymbols NETMF kann der Quellcode auch für das veraltete .NET Micro Framework übersetzt werden.

Migration von Version 1.x

Das in Version 1.x verwendete Typpräfix SL entfällt in Version 2.x.
Die auf Reflection basierenden Klassen wurden in die neue Bibliothek Liersch.JsonSerialization ausgelagert.

Parsen von JSON-Dokumenten

Die statische Funktion JsonNode.Parse sollte für das Parsen von JSON-Dokumenten verwendet werden. Dabei wird gleichzeitig die Syntax des JSON-Dokuments überprüft. Liegt eine Syntaxverletzung vor, wird die Ausnahme vom Typ JsonException generiert.

Alternativ kann eine Instanz der Klasse JsonParser erstellt werden. Verschiedene Eigenschaften dienen zur Festlegung der Arbeitsweise. Beispielsweise unterstützt JsonParser optional einfache Anführungszeichen.

public static void RunExample1()
{
  string json=@"
  {
    ""addressBook"": [
      {""lastName"": ""Average"", ""firstName"": ""Joe""},
      {""lastName"": ""Doe"", ""firstName"": ""Jane""},
      {""lastName"": ""Smith"", ""firstName"": ""John""}
    ]
  }";

  var root=JsonNode.Parse(json);
  JsonNode book=root["addressBook"];
  if(book.IsArray)
  {
    int c=book.Count;
    for(int i=0; i<c; i++)
    {
      JsonNode entry=book[i];
      string ln=entry["lastName"];
      string fn=entry["firstName"];
      Console.WriteLine(fn+" "+ln);
    }
  }
}

Die Klasse JsonNode

JsonNode ist die zentrale Klasse zum Speichern eines JSON-Dokuments. Sie bietet zahlreiche Funktionen und Eigenschaften zur Analyse und Bearbeitung. Operatoren erleichtern den lesenden und schreibenden Zugriff auf Werte. JsonNode implementiert IEnumerable, um die Werte eines Arrays oder Objekts zu liefern. Die Eigenschaft Names liefert für Objekte die Namen aller Eigenschaften.

public static void RunExample2()
{
  string json=RetrieveJsonExample();
  PrintNode(JsonNode.Parse(json), "demo = ", 0);
}

static void PrintNode(JsonNode node, string prefix, int level)
{
  Console.Write(new string(' ', level*2));
  Console.Write(prefix);

  switch(node.NodeType)
  {
    case JsonNodeType.Array:
      Console.WriteLine("(Array)");
      int c=node.Count;
      for(int i=0; i<c; i++)
        PrintNode(node[i], "["+i.ToString(CultureInfo.InvariantCulture)+"] = ", level+1);
      break;

    case JsonNodeType.Object:
      Console.WriteLine("(Object)");
      foreach(string name in node.Names)
        PrintNode(node[name], name+" = ", level+1);
      break;

    case JsonNodeType.Boolean:
    case JsonNodeType.Number:
    case JsonNodeType.String:
      Console.WriteLine(node.AsString+" ("+node.NodeType.ToString()+")");
      break;

    default:
      Console.WriteLine("("+node.NodeType.ToString()+")");
      break;
  }
}

Zum Lesen und Schreiben von Werten stehen die Eigenschaften AsBoolean, AsInt32, AsInt64, AsDouble und AsString zur Verfügung. Wenn ein Wert beim Lesen nicht in den jeweiligen Datentyp konvertiert werden kann, wird stattdessen der Standardwert, also 0 oder null zurückgegeben.

Das Lesen eines nicht vorhandenen Wertes oder der Zugriff über einen nicht vorhandenen Index liefert eine leere Instanz von JsonNode zurück. Schreibzugriffe auf nicht vorhandene Werte führen dazu, dass diese erzeugt werden. JsonNode kann auf diese Weise genutzt werden, um neue JSON-Dokumente zu generieren.

public static void RunExample3()
{
  var root=new JsonNode();
  root["addressBook"]=CreateAddressBook();
  Console.WriteLine(root.AsJson);
}

static JsonNode CreateAddressBook()
{
  var book=new JsonNode();

  book[0]["LastName"]="Average";
  book[0]["firstName"]="Joe";

  book[1]["LastName"]="Doe";
  book[1]["firstName"]="Jane";

  book[2]["LastName"]="Smith";
  book[2]["firstName"]="John";

  return book;
}

Die Klasse JsonMonitor

JsonNode.CreateMonitor erzeugt eine neue Instanz von JsonMonitor. Ein solcher Aufruf ist nur für Wurzelelemente und nur ein einziges Mal erlaubt.

JsonMonitor.IsModified zeigt mit true an, wenn ein untergeordneter Knoten oder der Wurzelknoten selbst geändert wurde. JsonMonitor.IsReadOnly dient dazu, Änderungen zu unterbinden. Werden Knoten an externen Code übergeben, kann diese Eigenschaft genutzt werden, um unerwünschte Seiteneffekte zu verhindern.

Die Klasse JsonWriter

JsonWriter dient zum Erzeugen von JSON-Dokumenten. Die Klasse ist minimalistisch implementiert. Sie verfügt über keine Prüfungen und arbeitet dadurch sehr effizienzt.

Lizenz

Die Veröffentlichung der Software erfolgt unter den Bedingungen einer Open-Source-Lizenz. Alternativ können im Rahmen einer kommerziellen Lizenz andere Bedingungen vereinbart werden. Sie können Pflege und Weiterentwicklung der Software mit einer freiwilligen Spende unterstützen.

Copyright

Verweise

Der Quellcode wird auf GitHub gepflegt:
https://github.com/steffen-liersch/Liersch.Json

Pakete können über NuGet heruntergeladen werden:
https://www.nuget.org/packages/Liersch.Json

Liersch.Json – JSON-Unterstützung für .NET