Modus voor brongeneratie in System.Text.Json
Brongeneratie kan worden gebruikt in twee modi: optimalisatie op basis van metagegevens en serialisatie. In dit artikel worden de verschillende modi beschreven.
Zie Brongeneratiemodi gebruiken in System.Text.Jsonvoor meer informatie over het gebruik van brongeneratiemodi.
Modus op basis van metagegevens
U kunt het genereren van de bron gebruiken om het proces voor het verzamelen van metagegevens te verplaatsen van runtime tot compileertijd. Tijdens de compilatie worden de metagegevens verzameld en worden broncodebestanden gegenereerd. De gegenereerde broncodebestanden worden automatisch gecompileerd als integraal onderdeel van de toepassing. Deze techniek elimineert het verzamelen van runtimemetagegevens, waardoor de prestaties van zowel serialisatie als deserialisatie worden verbeterd.
De prestatieverbeteringen die worden geboden door het genereren van bronnen, kunnen aanzienlijk zijn. Testresultaten hebben bijvoorbeeld tot 40% of meer opstarttijd, vermindering van het privégeheugen, doorvoersnelheidsverhoging (in serialisatieoptimalisatiemodus) en vermindering van de grootte van apps weergegeven.
Bekende problemen
Alleen public eigenschappen en velden worden standaard ondersteund in beide serialisatiemodussen. De weerspiegelingsmodus biedt echter ondersteuning voor het gebruik van private accessors, terwijl de brongeneratiemodus dat niet doet. U kunt bijvoorbeeld het kenmerk JsonInclude toepassen op een eigenschap met een private setter of getter en deze wordt geserialiseerd in de weerspiegelingsmodus. De brongeneratiemodus ondersteunt alleen public of internal accessors van public eigenschappen. Als u [JsonInclude] instelt op niet-openbare accessors en de modus voor het genereren van bronnen kiest, wordt er een NotSupportedException gegenereerd tijdens runtime.
Alleen public eigenschappen en velden worden standaard ondersteund in beide serialisatiemodussen. De weerspiegelingsmodus ondersteunt echter het gebruik van private leden en private accessors, terwijl de brongeneratiemodus dat niet doet. Als u bijvoorbeeld het kenmerk JsonInclude toepast op een private eigenschap of een eigenschap met een private setter of getter, wordt het geserialiseerd in de weerspiegelingsmodus. De brongeneratiemodus ondersteunt alleen public leden internal en public of internal toegangsrechten van public eigenschappen. Als u leden private of accessors instelt [JsonInclude] en de modus voor het genereren van bronnen kiest, wordt er een NotSupportedException gegenereerd tijdens de uitvoering.
Zie de GitHub-problemen met het label 'source-generator' in de dotnet-/runtime-opslagplaats voor meer informatie over andere bekende problemen met het genereren van bronnen.
Serialisatie-optimalisatiemodus (snel pad)
JsonSerializer heeft veel functies die de uitvoer van serialisatie aanpassen, zoals naamgevingsbeleid en verwijzingen behouden. Ondersteuning voor al deze functies veroorzaakt enige overhead voor prestaties. Het genereren van de bron kan de serialisatieprestaties verbeteren door geoptimaliseerde code te genereren die rechtstreeks wordt gebruikt Utf8JsonWriter .
De geoptimaliseerde code biedt geen ondersteuning voor alle serialisatiefuncties die JsonSerializer ondersteuning bieden. De serialisatiefunctie detecteert of de geoptimaliseerde code kan worden gebruikt en valt terug op standaardserialisatiecode als er niet-ondersteunde opties zijn opgegeven. Is bijvoorbeeld JsonNumberHandling.AllowReadingFromString niet van toepassing op schrijven, dus het opgeven van deze optie veroorzaakt geen terugval naar standaardcode.
In de volgende tabel ziet u in welke opties JsonSerializerOptions worden ondersteund door serialisatie van snelpaden:
| Serialisatieoptie | Ondersteund voor snel pad |
|---|---|
| AllowTrailingCommas | ✔️ |
| Converters | ❌ |
| DefaultBufferSize | ✔️ |
| DefaultIgnoreCondition | ✔️ |
| DictionaryKeyPolicy | ❌ |
| Encoder | ❌ |
| IgnoreNullValues | ❌ |
| IgnoreReadOnlyFields | ✔️ |
| IgnoreReadOnlyProperties | ✔️ |
| IncludeFields | ✔️ |
| MaxDepth | ✔️ |
| NumberHandling | ❌ |
| PropertyNamingPolicy | ✔️ |
| ReferenceHandler | ❌ |
| TypeInfoResolver | ✔️ |
| WriteIndented | ✔️ |
(De volgende opties worden niet ondersteund omdat ze alleen van toepassing zijn op deserialisatie: PropertyNameCaseInsensitive, ReadCommentHandlingen UnknownTypeHandling.)
In de volgende tabel ziet u welke kenmerken worden ondersteund door serialisatie van snelpaden:
| Kenmerk | Ondersteund voor snel pad |
|---|---|
| JsonConstructorAttribute | ❌ |
| JsonConverterAttribute | ❌ |
| JsonDerivedTypeAttribute | ✔️ |
| JsonExtensionDataAttribute | ❌ |
| JsonIgnoreAttribute | ✔️ |
| JsonIncludeAttribute | ✔️ |
| JsonNumberHandlingAttribute | ❌ |
| JsonPolymorphicAttribute | ✔️ |
| JsonPropertyNameAttribute | ✔️ |
| JsonPropertyOrderAttribute | ✔️ |
| JsonRequiredAttribute | ✔️ |
Als een niet-ondersteunde optie of kenmerk is opgegeven voor een type, valt de serializer terug op de metagegevensmodus, ervan uitgaande dat de brongenerator is geconfigureerd voor het genereren van metagegevens. In dat geval wordt de geoptimaliseerde code niet gebruikt bij het serialiseren van dat type, maar kan worden gebruikt voor andere typen. Daarom is het belangrijk om prestatietests uit te voeren met uw opties en workloads om te bepalen hoeveel voordeel u daadwerkelijk kunt krijgen van de serialisatie-optimalisatiemodus. De mogelijkheid om terug te vallen op JsonSerializer code vereist ook de modus voor het verzamelen van metagegevens. Als u alleen de serialisatieoptimalisatiemodus selecteert, kan serialisatie mislukken voor typen of opties die terug moeten vallen op JsonSerializer code.
