Modes de génération de source dans System.Text.Json

La génération de source peut être utilisée dans deux modes : l’optimisation basée sur les métadonnées et la sérialisation. Cet article présente les différents modes.

Pour plus d’informations sur l’utilisation des modes de génération source, consultez Comment utiliser la génération source dans System.Text.Json.

Mode basé sur les métadonnées

Vous pouvez utiliser la génération source pour déplacer le processus de collecte de métadonnées du runtime au moment de la compilation. Pendant la compilation, les métadonnées sont collectées et les fichiers de code source sont générés. Les fichiers de code source générés sont automatiquement compilés en tant que partie intégrante de l’application. Cette technique élimine la collecte de métadonnées d’exécution, ce qui améliore les performances de la sérialisation et de la désérialisation.

Les améliorations de performances apportées par la génération de source peuvent être substantielles. Par exemple, les résultats des tests ont montré jusqu’à 40 % ou plus de réduction du temps de démarrage, une réduction de la mémoire privée, une augmentation de la vitesse de débit (en mode d’optimisation de la sérialisation) et une réduction de la taille de l’application.

Membres et constructeurs non publics

Par défaut, le mode de réflexion et le mode de génération de source incluent uniquement les propriétés et champs public dans le contrat de sérialisation.

À compter de .NET 11, la génération source prend en charge les membres que vous marquez explicitement avec l’attribut [JsonInclude]. Le membre peut être private, internalou protected. Il prend également en charge les accesseurs private, internal et protected pour les propriétés que vous annotez avec [JsonInclude]. La génération de source prend également en charge les constructeurs inaccessibles marqués avec [JsonConstructor].

Sur .NET 11, les accesseurs générés utilisent UnsafeAccessorAttribute.

Un setter généré par la source pour une initpropriété -only s’exécute uniquement lorsque la charge utile JSON contient cette propriété. Une propriété init only que la charge utile omet conserve la valeur définie par son initialiseur de propriété.

Dans .NET versions 10 et antérieures, la génération de source présente les limitations suivantes :

  • La génération du code source ne prend pas en charge private ou les membres ou accesseurs protected. Si vous marquez un tel membre avec [JsonInclude], le sérialiseur lève un NotSupportedException au moment de l’exécution.
  • La génération de code source prend en charge les membres et accesseurs internal uniquement lorsqu’ils sont accessibles au JsonSerializerContext généré dans le même assembly.
  • La génération source ne prend pas en charge les constructeurs inaccessibles au contexte généré, même lorsque vous les marquez avec [JsonConstructor].

Problèmes connus

Pour plus d’informations sur les autres problèmes connus liés à la génération de source, consultez les problèmes GitHub étiquetés « source-generator » dans le référentiel dotnet/runtime.

Mode d’optimisation de la sérialisation (chemin rapide)

JsonSerializer possède de nombreuses fonctionnalités qui personnalisent la sortie de la sérialisation, comme les stratégies d’affectation de noms et la conservation des références. La prise en charge de toutes ces fonctionnalités entraîne une certaine surcharge de performances. La génération de source peut améliorer les performances de sérialisation en générant du code optimisé qui utilise Utf8JsonWriter directement.

Le mode d’optimisation de la sérialisation émet des méthodes de sérialisation rapides, mais pas des métadonnées de sérialisation. La sérialisation de chemin rapide est limitée dans ce qu’elle peut faire ; elle ne prend pas en charge la sérialisation asynchrone ou tout mode de désérialisation.

En outre, le code optimisé ne prend pas en charge toutes les fonctionnalités de sérialisation qui JsonSerializer prennent en charge. Le sérialiseur détecte si le code optimisé peut être utilisé et revient au code de sérialisation par défaut si des options non prises en charge sont spécifiées. Par exemple, JsonNumberHandling.AllowReadingFromString n’étant pas applicable à l’écriture, la spécification de cette option n’entraîne pas un retour vers le code par défaut.

Le tableau suivant indique les options de JsonSerializerOptions prises en charge par la sérialisation à chemin rapide :

Option de sérialisation Prise en charge pour le chemin d’accès rapide
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

(Les options suivantes ne sont pas prises en charge, car elles s’appliquent uniquement à la désérialisation : PropertyNameCaseInsensitive, ReadCommentHandling et UnknownTypeHandling.)

Le tableau suivant indique les attributs pris en charge par la sérialisation à chemin rapide :

Attribut Prise en charge pour le chemin d’accès rapide
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

Si une option ou un attribut non pris en charge est spécifié pour un type, le sérialiseur revient au mode de métadonnées, en supposant que le générateur source a été configuré pour générer des métadonnées. Dans ce cas, le code optimisé n’est pas utilisé lors de la sérialisation de ce type, mais il peut être utilisé pour d’autres types. Par conséquent, il est important d’effectuer des tests de performance avec vos options et charges de travail pour déterminer les avantages que vous pouvez réellement tirer du mode d’optimisation de la sérialisation. En outre, la possibilité de revenir au JsonSerializer code nécessite le mode de métadonnées. Si vous sélectionnez uniquement le mode d’optimisation de la sérialisation, cette dernière peut échouer pour les types ou les options qui doivent revenir au code JsonSerializer.

Voir aussi

  • Dernière mise à jour :