JSON.net ContractResolver vs. JsonConverter

Question

Je travaille avec JSON.net depuis un certain temps. J'ai écrit à la fois des convertisseurs personnalisés et des résolveurs de contrat personnalisés (généralement à partir de la modification d'exemples sur S.O. et le site Web de Newtonsoft), et ils fonctionnent bien.

Le problème, c'est qu'en dehors des exemples, je ne vois guère d'explications sur le moment où je dois utiliser l'un ou l'autre (ou les deux) pour le traitement. Par ma propre expérience, j'ai essentiellement déterminé que les résolveurs de contrat sont plus simples, donc si je peux faire ce dont j'ai besoin avec eux, je vais dans cette direction ; sinon, j'utilise des JsonConverters personnalisés. Mais, je sais aussi que les deux sont parfois utilisés ensemble, ainsi les concepts deviennent plus opaques.

Questions :

1. Existe-t-il une source qui distingue quand il faut utiliser l'un ou l'autre ? Je trouve que la documentation de Newtonsoft n'est pas claire quant à la façon dont les deux sont différenciés ou quand utiliser l'un ou l'autre.
2. Quel est le pipeline de commande entre les deux ?

Answer 1

Excellente question. Je n'ai pas vu de documentation claire indiquant quand il est préférable d'écrire un fichier personnalisé ContractResolver ou un JsonConverter pour résoudre un type particulier de problème. Ils font vraiment des choses différentes, mais il y a un certain chevauchement entre les types de problèmes qui peuvent être résolus par chacun. J'ai écrit un bon nombre d'articles sur chacun d'eux en répondant à des questions sur StackOverflow, de sorte que l'image est devenue un peu plus claire pour moi au fil du temps. Voici mon point de vue à ce sujet.

Résolveur de contrat

Un résolveur de contrat est toujours utilisé par Json.Net, et régit le comportement de sérialisation/désérialisation à un niveau général. S'il n'y a pas de résolveur personnalisé fourni dans les paramètres, alors l'attribut DefaultContractResolver est utilisé. Le résolveur est chargé de déterminer :

• ce que contrat chaque type a (c'est-à-dire s'agit-il d'une primitive, d'un tableau/liste, d'un dictionnaire, d'une dynamique ), JObject , un vieil objet, etc ;)
• quelles sont les propriétés du type (le cas échéant) et quels sont leurs noms, types et accessibilité ;
• ce que attributs ont été appliquées (par exemple [JsonProperty] , [JsonIgnore] , [JsonConverter] etc.), et
• comment ces attributs doivent affecter la (dé)sérialisation de chaque propriété (ou classe).

D'une manière générale, si vous souhaitez personnaliser un aspect de la sérialisation ou de la désérialisation dans un large éventail de classes, vous devrez probablement utiliser un fichier ContractResolver pour le faire. Voici quelques exemples de choses que vous pouvez personnaliser à l'aide d'une ContractResolver :

• Modifier le contrat utilisé pour un type
  • Sérialisez tous les dictionnaires comme un tableau de paires clé/valeur.
  • Serialize ListItems comme un objet régulier au lieu de la chaîne de caractères
• Changer la casse des noms de propriétés lors de la sérialisation
  • Utiliser la casse pour tous les noms de propriétés
  • Camel casse tous les noms de propriétés sauf les dictionnaires
• appliquer de manière programmée des attributs aux propriétés sans avoir à modifier les classes (particulièrement utile si vous ne contrôlez pas la source desdites classes)
  • Utiliser globalement un JsonConverter sur une classe sans l'attribut
  • Remapper les propriétés à des noms différents définis au moment de l'exécution
  • Autoriser la désérialisation des propriétés publiques avec des paramètres non publics.
• Par programmation ne pas appliquer (ignorer) les attributs qui sont appliqués à certaines classes
  • Désactiver de manière facultative l'attribut JsonIgnore au moment de l'exécution.
  • Faire en sorte que les propriétés qui sont marquées comme obligatoires (pour SOAP) ne le soient pas pour JSON.
• Sérialisation conditionnelle propriétés
  • Ignorer les propriétés en lecture seule dans toutes les classes
  • Sauter la sérialisation des propriétés qui lèvent des exceptions
• Introduire des attributs personnalisés et appliquer un comportement personnalisé basé sur ces attributs.
  • Cryptage des propriétés de chaînes spécialement marquées dans n'importe quelle classe
  • Échapper sélectivement le HTML dans les chaînes de caractères pendant la désérialisation

JsonConverter

Contrairement à un ContractResolver le centre d'intérêt d'un JsonConverter est plus étroite : elle est vraiment destinée à gérer la sérialisation ou la désérialisation d'un seul type ou d'un petit sous-ensemble de types apparentés. En outre, il travaille à un niveau inférieur à celui d'un résolveur. Lorsqu'un convertisseur se voit confier la responsabilité d'un type, il a un contrôle total sur la manière dont le JSON est lu ou écrit pour ce type : il utilise directement les fonctions JsonReader y JsonWriter pour faire son travail. En d'autres termes, il peut modifier le forme du JSON pour ce type. Dans le même temps, un convertisseur est découplé de la "vue d'ensemble" et n'a pas accès aux informations contextuelles telles que le parent de l'objet (dé)sérialisé ou les attributs de propriété qui ont été utilisés avec lui. Voici quelques exemples de problèmes que vous pouvez résoudre avec un JsonConverter :

• Gérer les problèmes d'instanciation d'objet lors de la désérialisation
  • Désérialisation vers une interface, en utilisant les informations contenues dans le JSON pour décider de la classe concrète à instancier.
  • Désérialisez JSON qui est parfois un objet unique et parfois un tableau d'objets.
  • Désérialise JSON qui peut être un tableau ou un tableau imbriqué.
  • Sauter les éléments non désirés lors de la désérialisation d'un tableau de types mixtes
  • Désérialiser vers un objet qui n'a pas de constructeur par défaut.
• Modifier la façon dont les valeurs sont formatées ou interprétées
  • Sérialiser les valeurs décimales en tant que chaînes de caractères localisées
  • Convertir decimal.MinValue en une chaîne vide et vice-versa. (pour une utilisation avec un système existant)
  • Sérialiser les dates avec plusieurs formats différents
  • Ignorer les décalages UTC lors de la désérialisation des dates
  • Faire un appel à Json.Net ToString() lors de la sérialisation d'un type
• Traduire entre différentes structures JSON et objets
  • Désérialise un tableau imbriqué de valeurs mixtes en une liste d'éléments.
  • Désérialise un tableau d'objets avec des noms différents.
  • Sérialisation/désérialisation d'un dictionnaire personnalisé avec des clés complexes
  • Sérialiser une collection IEnumerable personnalisée comme un dictionnaire
  • Aplatissez une structure JSON imbriquée en une structure objet plus simple.
  • Étendre une structure d'objet simple en une structure JSON plus compliquée
  • Sérialise une liste d'objets sous la forme d'une liste d'identifiants uniquement.
  • Désérialise une liste JSON d'objets contenant des GUIDs en une liste de GUIDs.
• Contourner les problèmes de (dé)sérialisation de types .NET spécifiques
  • La sérialisation de System.Net.IPAddress entraîne une exception.
  • Problèmes de désérialisation de Microsoft.Xna.Framework.Rectangle