Experte für JSON-Datenbindung

Aus RAD Studio
Wechseln zu: Navigation, Suche

Nach oben zu Menü "Datei"

Datei > Neu > Weitere... > Delphi > Web > JSON-Datenbindung

Der Experte für JSON-Datenbindung bietet eine einfache Möglichkeit, Delphi-Datentypen auf Grundlage einer JSON-Datenstruktur zu erstellen und diese Typen den JSON-Daten mithilfe einer der Delphi-Bibliotheken für JSON-Marshaling und -Serialisierung zuzuordnen.

Dieser Experte führt die Entwickler durch die verschiedenen Optionen und hilft ihnen bei der Erstellung neuer Units anhand der Datenzuordnung, die auf der vorhandenen JSON-Datenstruktur als Vorlage basiert.

Zusammenfassung: Funktionsweise

Der Experte übernimmt einen JSON-Text, analysiert ihn und generiert eine Reihe von Delphi-Typen.

Da JSON über keine offizielle oder weitverbreitete Schemadefinition verfügt, stellt das Ergebnis der Analyse die Typen dar, die am besten für die angegebenen JSON-Daten passen.

Der generierte Code ist für die angegebene JSON-Bibliothek optimiert, die Sie im Experten auswählen können. Gegenwärtig werden die folgenden Bibliotheken unterstützt:

Beispiel

Beispiel: Folgende JSON-Daten sind vorhanden: 

{"customer": {
 "id": 1,
 "name": "Mark",
 "phone": "(831) 431-1000"
}}

Der Experte generiert die folgenden Typen für die Bibliothek REST.Json: 

  [JsonSerialize(jmAllPubProps)]
  TCustomer = class(TPersistent)
  private
	Fid: Integer;
	Fname: string;
	Fphone: string;
  public
	property id: Integer read Fid write Fid;
	property name: string read Fname write Fname;
	property phone: string read Fphone write Fphone;
  end;

  [JsonSerialize(jmAllPubProps)]
  TData = class(TPersistent)
  private
	Fcustomer: TCustomer;
  public
	constructor Create;
	destructor Destroy; override;
	property customer: TCustomer read Fcustomer;
  end;

Dann kann die Anwendung diese Bibliothek oder die übergeordnete Thin-Klasse TJSONMapper<T> verwenden, um JSON-Daten in diese Typinstanzen zu laden oder Typinstanzen in JSON zu serialisieren.

Zum Beispiel mit REST.Json: 

  // Load JSON data from “s” string into new TData instance
  LData := TJson.JsonToObject<TData>(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJson.ObjectToJsonString(LData);

Oder mit TJSONMapper<T>: 

  // Set JSON library to use
  TJSONMapper<TData>.SetDefaultLibrary('REST.Json');

  // Load JSON data from “s” string into new TData instance
  LData := TJSONMapper<TData>.Default.ObjFrom(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJSONMapper<TData>.Default.ToStr(LData);

Verwenden des Experten für JSON-Datenbindung

Zuerst müssen Sie den Experten für JSON-Datenbindung über Datei > Neu > Weitere... > Delphi > Web > JSON-Datenbindung öffnen.

Führen Sie dann die folgenden Schritte aus:

Schritt 1: JSON-Quelle auswählen

JSON Data Binding Wizard JSON Source.png

Geben Sie auf der Seite JSON-Quelle die JSON-Quelle an, aus der Sie Delphi-Typen generieren möchten.

Folgende Alternativen sind möglich:

  • Aus Zwischenablage einfügen: Verwenden Sie den JSON-Text, der bereits in der Zwischenablage gespeichert ist. Diese Option ist nur verfügbar, wenn die Zwischenablage gültigen JSON-Text enthält.
  • In Eingabefeld eingeben: Ermöglicht die Eingabe des JSON-Textes in einen vom Experten bereitgestellten Editor.
  • Aus Datei lesen: Der Benutzer muss eine Datei mit JSON-Text angeben.
  • Von REST-Dienst abrufen: Importieren Sie den JSON-Text über eine HTTP GET-Anforderung aus einer URL, die auf der nächsten Seite angegeben wird.

Schritt 2: JSON eingeben, Datei bereitstellen oder REST-Dienst festlegen

Wenn der JSON-Text nicht aus der Zwischenablage kopiert wird, muss der Benutzer abhängig von der im vorherigen Schritt ausgewählten Option eine der folgenden Aktionen ausführen:

  • Den JSON-Text manuell in das Eingabefeld eingeben
  • Den Pfad zu der Datei mit dem JSON-Text angeben
  • Eine Endpunkt-URL, einen Benutzernamen und ein Passwort angeben.
Hinweis: Nachdem Sie auf die Schaltfläche Weiter geklickt haben, ruft der Experte den JSON-Text ab, analysiert ihn und zeigt ein Meldungsfeld an, wenn Fehler gefunden werden.

Schritt 3: Bindungsoptionen angeben

JSON Data Binding Wizard Binding Options.png

Geben Sie auf der Seite Bindungsoptionen an, wie die JSON-Elemente zu Delphi-Elementen zugeordnet/an diese gebunden werden sollen. Hier können Sie eine der verfügbaren Zuordnungsbibliotheken und weitere Einstellungen der Zuordnungslogik auswählen.

Folgende Optionen sind verfügbar:

  • JSON-Zuordnungsbibliothek: JSON-Marshaling-/Serialisierungsbibliothek, für die die Delphi-Typen generiert werden müssen. Optionen:
    • System.JSON.Serializers
    • REST.Json
  • JSON-Array zuordnen zu: Der Delphi-Datentyp, der beim Zuordnen von JSON-Arrays verwendet wird. Die möglichen Optionen sind:
    • TArray
    • TList (einige JSON-Bibliotheken, wie REST.Json, unterstützen die direkte "TList"-Zuordnung zu JSON-Arrays möglicherweise nicht).
  • JSON-Objekt zuordnen zu: Der Delphi-Datentyp, der beim Zuordnen von JSON-Objekten verwendet wird. Die möglichen Optionen sind:
    • TObject
    • record (einige JSON-Bibliotheken, wie REST.Json, unterstützen den Typ "record" möglicherweise nicht).
  • JSON-Member zuordnen zu: Der Delphi-Datentyp, der beim Zuordnen von JSON-Objekt-Membern verwendet wird. Die möglichen Optionen sind:
    • Eigenschaft
    • Feld
  • JSON-String zuordnen zu: Der Delphi-Datentyp, der beim Zuordnen von JSON-Stringwerten verwendet wird. Die möglichen Optionen sind:
    • Unicode
    • Ansi
  • Eigenschaftszugriff: Diese Optionen bestimmen den Code der Klasse, die generiert wird. Die möglichen Optionen sind:
    • Felder
    • Getter
    • Setter
    • Getter und Setter
    Hinweis: Die JSON-Informationen werden über Eigenschaften zu Feldern zugeordnet, aber Sie können auch festlegen, dass diese Eigenschaften direkt zu Feldern zugeordnet werden: zu Feldern beim Lesen, zu Setter-Methoden beim Schreiben oder umgekehrt (allerdings sehr ungewöhnlich) oder zu zwei Methoden zum Lesen und Schreiben.

Schritt 4: Codeoptionen auswählen

JSON Data Binding Wizard Code Options.png

Geben Sie auf der Seite Codeoptionen an, wie die Delphi-Entitäten benannt werden sollen.

Folgende Optionen sind verfügbar:

  • Basisklassenname: Klassenname, von dem alle generierten Entitätstypen geerbt werden, wenn auf der vorherigen Seite die Option "JSON-Objekt zuordnen zu" auf TObject festgelegt ist (hat für "record" keine Bedeutung).
  • Name des Root-Objekttyps: Der Name der äußersten Delphi-Entität, der das äußerste JSON-Objekt zugeordnet werden soll.
  • Name des Root-Array-Typs: Optional. Der Name der Delphi-Entität, die das Array der „Root“-Entitäten repräsentiert. Wenn der Name des Root-Array-Typs nicht angegeben ist, wird der entsprechende Delphi-Entitätstyp nicht generiert. Wenn angegeben, wird die Entität wie folgt generiert, wobei es sich um eine einzelne Dataset-Eigenschaft handelt:
[JsonSerialize(jmFields)]
TDataArray = class(TPersistent)
private
FDataset: TArray<TData>;
  public
	destructor Destroy; override;
	property Dataset: TArray<TData> read FDataset write FDataset;
  End;

Klicken Sie auf die Schaltfläche Fertig stellen, um den Quellcode zu erzeugen.

Zuordnungsregeln

Der Experte für JSON-Datenbindung verwendet die folgenden Datenzuordnungsregeln:

  • JSON-Objekt zuordnen zu Delphi-TObject oder -Record: Der genaue Typ hängt von der Einstellung von JSON-Objekt zuordnen zu und davon ab, ob die JSON-Bibliothek Delphi-Records unterstützt (die REST.Json-Bibliothek unterstützt Records nicht).
  • JSON-Array zuordnen zu Delphi-TList<T> oder -TArray<T>: Der genaue Typ hängt von der Einstellung von JSON-Array zuordnen zu und davon ab, ob die JSON-Bibliothek Delphi-TList<T> aus dem JSON-Array direkt deserialisieren/serialisieren kann. Die REST.Json-Bibliothek unterstützt TList<T> nicht, anstatt zu einem JSON-Array, wird es zu einem JSON-Objekt mit verschachteltem Array zugeordnet.
  • JSON-Member zuordnen zu einem Delphi-Feld oder einer Delphi-Eigenschaft. Der genaue Typ hängt von der Einstellungen von JSON-Member zuordnen zu und JSON-Objekt zuordnen zu ab. Eigenschaftstypen werden für den Typ "record" nicht unterstützt.
    • Wenn JSON-Objekte in einem JSON-Array gesammelt werden, wird der Feld-/Eigenschaftstyp durch Analyse der Werte von bis zu 1.000 Objekten abgeleitet. Der Experte kann Datums- und Zeitwerte, TGUIDs, boolesche Werte und mehr präzise verarbeiten.
    • Der Name des Feldes/der Eigenschaft entspricht dem JSON-Membernamen, wenn der JSON-Membername ein gültiger Delphi-Bezeichner ist. Andernfalls wird der Name so "geändert", dass er ein gültiger Bezeichner ist. Darüber hinaus wird Feldern der Buchstabe "F" vorangestellt.
  • Der Experte führt die "Bindung" der ausgewählten JSON-Bibliothek durch. Dies umfasst drei Elemente:
    • Fügt jedem TObject- oder Record-Typ ein Attribut hinzu, das angibt, welche Member bei der Serialisierung zu verwenden sind. Zum Beispiel:
      [JsonSerialize(jmAllPubProps)]
  TCustomer = class(TPersistent)
    • Fügt ein Attribut zu TObject- oder Record-Typ-Membern hinzu, wenn sein Name vom JSON-Membernamen abweicht. Zum Beispiel:
      [JsonName('label')]
    property label_: string read Flabel_ write Flabel_;
    • Fügt eine Bibliotheks-Unit, in der die oben genannten Attribute deklariert sind, der generierten uses-Klausel der Unit hinzu. Zum Beispiel:
      uses
    System.Classes, REST.Json.Types;
Hinweis: Der Experte für JSON-Datenbindung verwendet die Klasse Data.DBJson.TJSONToDataSetBridge, um die JSON-Struktur zu analysieren und die Sammlung Data.DB.TFieldDefs zu füllen. Anschließend generiert der Experte anhand dieser Sammlung die Delphi-Typen.

Verwendung der generierten Typen

Die generierten Delphi-Typen können mit der JSON-Bibliothek verwendet werden, die im Experten ausgewählt wurde. Es sind keine weiteren Änderungen erforderlich. Wenn die Bibliothekszuordnung geändert werden muss, sollten Sie den Experten erneut ausführen und die erforderliche Bibliothek auswählen.

Wenn Sie beispielsweise die REST.Json verwenden, erhalten Sie den folgenden Code: 

  // Load JSON data from “s” string into new TData instance
  LData := TJson.JsonToObject<TData>(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJson.ObjectToJsonString(LData);

Eine Alternative wäre hier, die generische Klasse System.JSON.TJSONMapper zu verwenden. Dies ist ein dünner Wrapper für bestehende JSON-Bibliotheken. Sie bietet eine vereinfachte API für die meisten gängigen JSON-Serialisierungs-/Deserialisierungsoperationen, obwohl sie Optionen und zusätzliche spezifische APIs verbirgt, die von den Bibliotheken bereitgestellt werden. Zum Beispiel: 

  // Set JSON library to use
  TJSONMapper<TData>.SetDefaultLibrary('REST.Json');

  // Load JSON data from “s” string into new TData instance
  LData := TJSONMapper<TData>.Default.ObjFrom(s);

  // Serialize TData instance referenced by LData into JSON string
  s := TJSONMapper<TData>.Default.ToString(LData);

Weitere Informationen finden Sie unter System.JSON.TJSONMappers.

Siehe auch

Abgerufen von „https://docwiki.embarcadero.com/RADStudio/Athens/d/index.php?title=Experte_für_JSON-Datenbindung&oldid=220067“