Référence CrystalJson

Les tables de référence du travail quotidien : le setup du générateur de source, les attributs que vous posez sur un type, les settings que vous passez à un appel, et les diagnostics de build que vous pouvez rencontrer. Pour les guides pratiques, voir Travailler avec CrystalJson ; pour la conception, voir Ce que c'est, et pourquoi. Quand un comportement a changé entre deux versions, le guide de migration 7.4.2 vers 7.4.3 porte l'histoire complète, et cette page y renvoie plutôt que de la répéter.

Tous les exemples utilisent using SnowBank.Data.Json;.

Setup

Les types d'exécution de CrystalJson (JsonValue, CrystalJson, CrystalJsonSettings) vivent dans SnowBank.Core. Un projet qui référence SnowBank.Core sérialise, parse et utilise le DOM via le chemin par réflexion sans autre setup.

Les convertisseurs générés et les proxies typés demandent en plus le générateur de source. Il est distribué comme un package séparé que le compilateur exécute comme un analyzer Roslyn. C'est un outil de build, pas une partie de votre application livrée ; SnowBank.Core est la seule dépendance d'exécution :

<!-- exécution : le DOM JsonValue et l'API CrystalJson -->
<PackageReference Include="SnowBank.Core" Version="7.4.6" />
<!-- build seulement : le générateur de source, un analyzer Roslyn, non redistribué avec votre app -->
<PackageReference Include="SnowBank.Serialization.Json.CodeGen" Version="7.4.6" />

Donnez aux deux la même version que vos autres packages SnowBank, ou omettez la version en gestion centralisée des packages. Le générateur demande C# 9 ou plus : en dessous, il rapporte SYSLIB1221 et n'émet rien, JSON compris, donc mettez <LangVersion> à 9 ou plus (le déclencheur classique est un projet porté qui pinne encore un <LangVersion>7.3</LangVersion> d'époque .NET Framework).

Un container est une classe partial qui déclare les types qu'elle sérialise. Les membres générés atterrissent dedans :

[CrystalJsonConverter]
[CrystalSerializable(typeof(Book))]
public static partial class AcmeSerializers { }

string json = AcmeSerializers.Book.ToJsonText(book);
Book back = AcmeSerializers.Book.Deserialize(json);

Attributs de container

Le container déclare trois choses indépendantes : quelle classe héberge le code, quels formats elle produit, et quels types elle enregistre.

Un profil passé à [CrystalJsonOutput(...)] ou [CrystalJsonConverter(...)] fixe la forme de sortie par défaut du container, CrystalJsonSerializerDefaults.Web pour le camelCase, .DataContractCompat pour le format historique de DataContractJsonSerializer. Des settings passés au site d'appel remplacent le profil pour cet appel.

[CrystalSerializable] remplace l'ancien [CrystalJsonSerializable] ; l'enregistrement est désormais neutre vis-à-vis du format. La sortie XML a ses propres attributs et sa propre page, CrystalXml.

Attributs de membre

Posez-les sur une propriété ou un champ pour changer la sérialisation de ce seul membre. Tous sont honorés sur le chemin par réflexion comme sur le chemin généré.

[JsonIgnore(Condition = ...)] lit JsonIgnoreCondition, en suivant le sens de System.Text.Json. Attention au piège de nommage : Never veut dire « ne jamais ignorer ».

Pour les types [DataContract], [DataMember(Name = ...)] renomme et [DataMember(IsRequired = true)] fait throw à la lecture quand le membre est absent. Les containers générés appliquent le modèle d'appartenance DataContract depuis la 7.4.3 ; le guide de migration en donne le détail.

Attributs d'autres sérialiseurs

CrystalJson lit les attributs qu'un DTO existant porte déjà de System.Text.Json et de Newtonsoft.Json (JSON.NET), donc un type porté se sérialise sans réannotation, à l'identique sur les deux chemins :

Quand plusieurs attributs de nommage s'accordent, le nom effectif vient du plus prioritaire : CrystalJson [JsonProperty], puis [JsonPropertyName], puis Newtonsoft [JsonProperty]. Deux attributs de nommage qui divergent sont une erreur de build (CJSON0011) : un type ne peut pas servir deux contrats de sortie. Un [DataMember] sur un type [DataContract] compte comme l'un d'eux même nu, parce qu'il nomme le membre d'après lui-même : un [JsonProperty] qui renomme ce même membre est le même conflit. Un [JsonConverter] étranger qui nomme un type n'implémentant pas le contrat de convertisseur CrystalJson est ignoré, pas une erreur, donc un DTO à moitié porté reste sérialisable. Le guide de migration donne les règles d'interop complètes.

Settings

Passez un CrystalJsonSettings à un appel Serialize, Parse, ou Deserialize. Partez d'un preset et ajoutez des modificateurs fluents ; chaque modificateur rend une nouvelle instance en cache.

Presets :

Modificateurs courants :

JsonStrict ne couvre pas les clés dupliquées ; ajoutez .ThrowOnDuplicateFields() quand une clé répétée doit échouer. Pour durcir le parser face à un input non fiable, voir Durcir le parsing d'un input non fiable.

Pour lire plusieurs documents consécutifs dans un même buffer, utilisez CrystalJson.ParseFragment, pas WithTrailingData() (qui parse la première valeur et jette le reste).

Défauts

• Les enums se sérialisent par leur nom, pas leur nombre. La lecture accepte les noms (insensible à la casse), les nombres et les nombres en string, quels que soient les settings.
• Le parser est permissif par défaut : les commentaires JavaScript et les virgules finales sont acceptés. C'est faux pour un input que vous ne contrôlez pas ; resserrez-le avec JsonStrict.
• Les nombres gardent leur littéral d'origine sur la route DOM tant que vous ne les lisez pas comme une valeur typée.

Diagnostics

Les codes CJSON#### ci-dessous sont ceux qu'un auteur normal rencontre en écrivant des DTO. Chacun est rapporté au même endroit par les deux chemins : le générateur émet le diagnostic, et le chemin par réflexion throw le même message quand il construit le contrat du type. Le guide de migration donne le traitement complet de chacun.

Les diagnostics des types auto-sérialisables (CJSON0004 à CJSON0007, CJSON0020, CJSON0021) et les codes du générateur XML (CRYS####, CXML####) sont couverts dans le guide de migration et CrystalXml.