Règles de sérialisation JSON (ADO.NET Data Services Framework)

Le format JSON utilisé par ADO.NET Data Services inclut des protocoles pour la sérialisation des données appliquées à toutes les ressources accessibles par le biais du service.

Règles de sérialisation communes à toutes les ressources

Cette rubrique répertorie les règles de sérialisation communes à toutes les ressources dans ADO.NET Data Services.

Remarque
Une grande partie des complexités liées à la sérialisation peuvent être atténuées en utilisant une bibliothèque qui effectue une conversion à partir de et vers le format JSON. Pour plus d'informations, consultez CodePlex.

Valeurs NULL

Toutes les valeurs NULL doivent être représentées à l'aide du littéral JSON 'null'.

Jeu d'entités

• Un jeu d'entités doit être représenté en tant que tableau d'objets JSON, avec un objet pour chaque instance de type d'entité dans le jeu.

• Un jeu d'entités vide doit être représenté en tant que tableau JSON vide, autrement dit un tableau avec zéro élément.

Type d'entité

• Un type d'entité doit être sérialisé en tant qu'objet JSON.

• Chaque propriété sur le type doit être représentée en tant que paire nom/valeur dans l'objet. Le nom dans la paire nom/valeur est le nom de la propriété et la valeur de la paire est la valeur de la propriété. L'ordre dans lequel les propriétés apparaissent dans un objet n'a pas d'importance.

• La sérialisation JSON d'une instance de type d'entité doit inclure une propriété nommée __metadata. Cette propriété ne constitue pas des données, mais plutôt une convention définie dans ce protocole afin de spécifier les métadonnées pour une instance spécifique d'un type. La valeur de la propriété __metadata contient deux propriétés : uri et type. La propriété uri doit être un URI identifiant l'instance de type d'entité actuelle. Plus spécifiquement, l'URI doit être relatif à l'URI demandeur après la suppression du dernier segment de chemin d'accès non vide. La valeur de la propriété 'Type' doit être le nom qualifié par l'espace de noms, par exemple namespaceName.typeName, du type qui représente l'instance de type d'entité sur le serveur. La propriété __metadata peut contenir une propriété etag. La propriété etag doit être présente si l'entité possède une propriété etag définie.

  • La propriété Type doit être incluse si le type d'entité représenté par l'objet JSON fait partie d'une hiérarchie d'héritage. Si ce n'est pas le cas, la propriété 'Type' est facultative.

  • Pour plus de détails sur les cas dans lesquels les paramètres URI et type doivent, peuvent ou ne doivent pas être présents, consultez Spécifications HTTP courantes.

Type complexe

• Un type complexe doit être sérialisé en tant qu'objet JSON.

• Chaque propriété du type complexe doit être représentée en tant que paire nom/valeur dans l'objet JSON. Le nom dans la paire nom/valeur est le nom de la propriété et la valeur de la paire est la valeur de la propriété. L'ordre dans lequel les propriétés apparaissent dans un objet n'a pas d'importance.

Propriété de navigation et propriété de lien

• La sérialisation des propriétés de navigation et de lien est différée par défaut. Lorsque le contenu est différé, la propriété uri sous l'élément __deferred ne contient pas l'URI canonique. Pour plus d'informations sur la manière d'étendre la propriété, consultez Contenu différé (JASON)..

• Étant donné que les propriétés de navigation et de lien représentent une association à un jeu d'entités connexe, la sérialisation d'une propriété de navigation est soumise aux mêmes règles que les jeux d'entités, avec l'exception suivante :

  • L'élément XML de niveau supérieur doit correspondre au nom de la propriété de navigation ou de lien, plutôt qu'à un nom de jeu d'entités.

Propriété

Une propriété peut être sérialisée de deux manières : avec du balisage d'habillage ou sous une forme non décorée (sans balisage d'habillage).

Pour utiliser la sérialisation d'une propriété en JSON avec le balisage d'habillage :

• La sérialisation est représentée en tant que paire nom/valeur dans un objet JSON, par exemple {<propertyname>:<propertyvalue>}.

• Le tableau fourni dans ce document illustre la façon dont chaque type primitif défini par le modèle EDM (Entity Data Model) est mis en forme à l'aide de JSON. La colonne de sérialisation JSON définit la manière dont une valeur de propriété est sérialisée.

Pour utiliser la sérialisation d'une propriété en JSON sans balisage d'habillage (URI se terminant par /$value) :

• Dans cette forme, seule la valeur de la propriété est sérialisée. La colonne de sérialisation JSON du tableau suivant spécifie la façon dont chaque type primitif est sérialisé dans cette forme.

• Si la valeur du type est NULL ou vide, il n'y a aucune sérialisation de la valeur de propriété dans cette forme. Dans ces cas-là, le modèle d'interaction de protocole doit signaler l'existence de telles valeurs.

Type primitif EDM	Sérialisation JSON	Représentation NULL (avec balisage d'habillage uniquement)	Représentation de valeur vide (avec balisage d'habillage uniquement)
Edm.Binary	Convert.ToBase64String(<bytes>, Base64FormattingOptions.None)	Non disponible	tableau de taille 0
Edm.Boolean	true | false	Non disponible	Non disponible
Edm.Byte	<short>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.DateTime	\/Date(<ticks>)\/ <ticks>: nombre de millisecondes écoulées depuis le 1er janvier 1970. Remarque : ce format est identique à celui utilisé par ASP.NET AJAX framework. Pour plus de détails, consultez DateTime. Pour obtenir un exemple avec ADO.NET Data Services, consultez HttpWebRequest POST (ADO.NET Data Services Framework).	Non disponible	Non disponible
Edm.Decimal	<Decimal>.ToString(CultureInfo.InvariantCulture). Remarque : JSON n'offre pas de type de données Decimal ; la valeur est convertie en chaîne afin de prévenir la perte de données.	Non disponible	Non disponible
Edm.Double	XmlConvert.ToString(<double>)	Non disponible	Non disponible
Edm.Guid	<Guid>. ToString() xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx	Non disponible	Non disponible
Edm.Int16	<int16>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.Int32	<int32>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.Int64	<int64>.ToString(CultureInfo.InvariantCulture). Remarque : retourné en tant que chaîne afin de prévenir la perte de données en raison des limitations liées aux nombres JSON.	Non disponible	Non disponible
Edm.SByte	<short>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.Single	XmlConvert.ToString(<float>). Si la valeur est l'infini, 'infinity' est utilisé.	Non disponible	Non disponible
Edm.String	<string>	null	""
Edm.UInt16	<uint16>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.UInt32	<uint32>.ToString(CultureInfo.InvariantCulture)	Non disponible	Non disponible
Edm.UInt64	<uint64>.ToString(CultureInfo.InvariantCulture). Remarque : retourné en tant que chaîne afin de prévenir la perte de données en raison des limitations liées aux nombres JSON.	Non disponible	Non disponible
System.Data.Linq.Binary	Convert.ToBase64String(<binary>.ToArray(),Base64FormattingOptions.None)	Non disponible	tableau de taille 0
System.Data.Linq.XElement	<element>.ToString(System.Data.Linq.SaveOptions.None)	null	""

Voir aussi

Concepts

Format JSON (ADO.NET Data Services Framework)
Contenu différé (JSON ADO.NET Data Services Framework)
ADO.NET Data Services Framework