JSON-Serialisierungsregeln (ADO.NET Data Services-Framework)

Das von den ADO.NET Data Services verwendete JSON-Format umfasst Protokolle für die Serialisierung von Daten, die auf alle über den Dienst verfügbaren Ressourcen angewendet werden.

Von allen Ressourcen verwendete Serialisierungsregeln

In diesem Thema werden die von allen Ressourcen in den ADO.NET Data Services verwendeten Serialisierungsregeln erläutert.

Hinweis
Viele Komplexitäten bei der JSON-Serialisierung können verringert werden, indem für die Konvertierung in bzw. aus dem JSON-Format eine Bibliothek verwendet wird. Weitere Informationen finden Sie unter CodePlex.

NULL-Werte

Alle NULL-Werte müssen mithilfe der literalen JSON-'NULL' dargestellt werden.

Entitätenmenge

• Eine Entitätenmenge muss als ein Array von JSON-Objekten dargestellt werden. Dabei muss ein Objekt jeweils eine Entitätstypeninstanz innerhalb der Menge darstellen.

• Eine leere Entitätenmenge muss als leeres JSON-Array dargestellt werden, d. h. ein Array mit null Elementen.

Entitätstyp

• Ein Entitätstyp muss als ein JSON-Objekt serialisiert werden.

• Jede Eigenschaft des Typs muss als Name/Wertpaar innerhalb des Objekts dargestellt werden. Der Name im Name/Wertpaar ist der Eigenschaftsname und der Wert des Paars ist der Wert der Eigenschaft. Die Reihenfolge, in der Eigenschaften innerhalb eines Objekts angezeigt werden, ist nicht von Bedeutung.

• Die JSON-Serialisierung einer Entitätstypeninstanz muss eine Eigenschaft mit dem Namen __metadata beinhalten. Diese Eigenschaft hat kein Datenformat, sondern ist eine in diesem Protokoll definierte Konvention, mit der die Metadaten für eine spezifische Instanz eines Typs angegeben werden. Der Wert der __metadata-Eigenschaft enthält die beiden Eigenschaften uri und type. Die uri-Eigenschaft muss ein URI sein, der die aktuelle Entitätstypeninstanz identifiziert. Dies bedeutet, dass der URI relativ zum anfordernden URI sein muss, nachdem das letzte nicht leere Pfadsegment entfernt wurde. Der Wert der 'Type'-Eigenschaft muss der als Namespace qualifizierte Name des Typs sein, der die gesamte Entitätstypeninstanz auf dem Server darstellt, beispielsweise namespaceName.typeName. Die __metadata-Eigenschaft kann eine etag-Eigenschaft enthalten. Die etag-Eigenschaft muss vorhanden sein, wenn für die Entität eine etag-Eigenschaft definiert ist.

  • Die Type-Eigenschaft muss enthalten sein, wenn der durch das JSON-Objekt dargestellte Entitätstyp Teil einer Vererbungshierarchie ist. Ist dies nicht der Fall, ist die 'Type'-Eigenschaft optional.

  • Weitere Informationen darüber, wann die URI- und type-Parameter vorhanden sein müssen, vorhanden sein können bzw. nicht vorhanden sein dürfen, finden Sie unter Allgemeine HTTP-Anforderungen.

Komplexer Typ

• Ein komplexer Typ muss als ein JSON-Objekt serialisiert werden.

• Jede Eigenschaft des komplexen Typs muss als Name/Wertpaar innerhalb des JSON-Objekts dargestellt werden. Der Name im Name/Wertpaar ist der Eigenschaftsname und der Wert des Paars ist der Wert der Eigenschaft. Die Reihenfolge, in der die Eigenschaften innerhalb eines Objekts angezeigt werden, ist nicht von Bedeutung.

Navigationseigenschaft und Verknüpfungseigenschaft

• Die Serialisierung von Navigations- und Verknüpfungseigenschaften wird standardmäßig verzögert. Wenn der Inhalt verzögert wird, enthält die uri-Eigenschaft unter dem __deferred-Element nicht den kanonischen URI. Weitere Informationen zum Erweitern der Eigenschaft finden Sie unter Verzögerte Inhalte (JASON).

• Da Navigations- und Verknüpfungseigenschaften eine Zuordnung zu einer zugehörigen Entitätenmenge darstellen, folgt das Serialisieren einer Navigationseigenschaft denselben Regeln wie bei Entitätenmengen, mit der folgenden Ausnahme:

  • Das XML-Element der höchsten Ebene muss mit dem Namen der Navigations- oder Verknüpfungseigenschaft übereinstimmen, nicht mit dem einer Entitätenmenge.

Eigenschaft

Eine Eigenschaft kann auf zweierlei Weise serialisiert werden: durch Wrapping-Markup oder in undekorierter Form ohne jegliches Wrapping-Markup.

So serialisieren Sie eine Eigenschaft nach JSON mit Wrapping-Markup:

• Die Serialisierung wird dargestellt als Name/Wertpaar innerhalb eines JSON-Objekts, wie zum Beispiel {<propertyname>:<propertyvalue>}.

• Die Tabelle in diesem Dokument zeigt, wie die einzelnen durch Entity Data Model (EDM) definierten primitiven Typen mithilfe von JSON formatiert werden. In der JSON-Serialisierungsspalte wird definiert, wie ein Eigenschaftswert serialisiert wird.

So serialisieren Sie eine Eigenschaft nach JSON ohne Wrapping-Markup (URIs enden mit /$value):

• Bei dieser Form wird nur der Wert der Eigenschaft serialisiert. In der JSON-Serialisierungsspalte der folgenden Tabelle wird angegeben, wie die einzelnen primitiven Typen in dieser Form serialisiert werden.

• Wenn der Wert vom Typ NULL oder leer ist, findet keine Serialisierung des Werts der Eigenschaft in dieser Form statt. In solchen Fällen muss das Interaktionsmodell des Protokolls das Vorhandensein solcher Wert signalisieren.

EDM-Primitiver Typ	JSON-Serialisierung	NULL-Darstellung (nur mit Wrapping-Markup)	Darstellung durch leeren Wert (nur mit Wrapping-Markup)
Edm.Binary	Convert.ToBase64String(<bytes>, Base64FormattingOptions.None)	Nicht verfügbar	Array der Größe 0
Edm.Boolean	true|false	Nicht verfügbar	Nicht verfügbar
Edm.Byte	<short>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.DateTime	\/Date(<ticks>)\/ <ticks>: Anzahl der Millisekunden seit 1. Januar 1970. Hinweis: Dieses Format entspricht dem vom ASP.NET AJAX-Framework verwendeten Format. Weitere Informationen finden Sie unter DateTime. Ein Beispiel für die Verwendung der ADO.NET Data Services finden Sie unter HttpWebRequest POST (ADO.NET Data Services-Framework).	Nicht verfügbar	Nicht verfügbar
Edm.Decimal	<Decimal>.ToString(CultureInfo.InvariantCulture). Hinweis: JSON verfügt nicht über einen Decimal-Datentyp. Der Wert wird in eine Zeichenfolge konvertiert, um den Verlust von Daten zu vermeiden.	Nicht verfügbar	Nicht verfügbar
Edm.Double	XmlConvert.ToString(<double>)	Nicht verfügbar	Nicht verfügbar
Edm.Guid	<Guid>. ToString() xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Nicht verfügbar	Nicht verfügbar
Edm.Int16	<int16>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.Int32	<int32>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.Int64	<int64>.ToString(CultureInfo.InvariantCulture). Hinweis: Wird aufgrund von JSON-Beschränkungen der Anzahl als Zeichenfolge zurückgegeben, um den Verlust von Daten zu vermeiden.	Nicht verfügbar	Nicht verfügbar
Edm.SByte	<short>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.Single	XmlConvert.ToString(<float>). Wenn der Wert unendlich ist, muss 'infinity' verwendet werden.	Nicht verfügbar	Nicht verfügbar
Edm.String	<string>	NULL	""
Edm.UInt16	<uint16>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.UInt32	<uint32>.ToString(CultureInfo.InvariantCulture)	Nicht verfügbar	Nicht verfügbar
Edm.UInt64	<uint64>.ToString(CultureInfo.InvariantCulture). Hinweis: Wird aufgrund von JSON-Beschränkungen der Anzahl als Zeichenfolge zurückgegeben, um den Verlust von Daten zu vermeiden.	Nicht verfügbar	Nicht verfügbar
System.Data.Linq.Binary	Convert.ToBase64String(<binary>.ToArray(),Base64FormattingOptions.None)	Nicht verfügbar	Array der Größe 0
System.Data.Linq.XElement	<element>.ToString(System.Data.Linq.SaveOptions.None)	NULL	""

Siehe auch

Konzepte

JSON-Format (ADO.NET Data Services-Framework)
Verzögerte Inhalte (JSON ADO.NET Data Services-Framework)
ADO.NET Data Services-Framework