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 van runtime naar de compileertijd te verplaatsen. 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. Voorbeeld testresultaten hebben tot 40% of meer vermindering van opstarttijd, vermindering van het privégeheugen, verhoging van de doorvoersnelheid (in de serialisatieoptimalisatiemodus) en vermindering van de app-grootte aangetoond.

Niet-openbare leden en constructors

Standaard bevatten zowel de weerspiegelingsmodus als de modus voor het genereren van bronnen alleen public eigenschappen en velden in het serialisatiecontract.

Vanaf .NET 11 ondersteunt de brongeneratie leden die u expliciet markeert met het kenmerk [JsonInclude].. Het lid kan private, internal of protected. Het ondersteunt ook private-, internal- en protected-accessors voor eigenschappen die u markeert met [JsonInclude]. Brongeneratie biedt ook ondersteuning voor niet-toegankelijke constructors die zijn gemarkeerd met [JsonConstructor].

Op .NET 11 gebruiken de gegenereerde accessors UnsafeAccessorAttribute.

Een brongegenereerde setter voor een alleen-lezeneigenschap van init wordt alleen aangeroepen wanneer de JSON-payload die eigenschap bevat. Een init-eigenschap die in de payload ontbreekt, behoudt de waarde van de initialisatiewaarde van de eigenschap.

In .NET 10 en eerdere versies heeft het genereren van de bron de volgende beperkingen:

  • Brongeneratie ondersteunt geen private-leden of protected-toegangsmethoden. Als u een dergelijk lid met [JsonInclude] markeert, werpt de serializer tijdens de uitvoering een NotSupportedException op.
  • Brongeneratie ondersteunt alleen internal-leden en accessors wanneer deze toegankelijk zijn voor de gegenereerde JsonSerializerContext in dezelfde assembly.
  • Brongeneratie biedt geen ondersteuning voor constructors die niet toegankelijk zijn voor de gegenereerde context, zelfs niet wanneer u ze markeert met [JsonConstructor].

Bekende problemen

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 beleid voor naamgeving en behouden van verwijzingen. Ondersteuning voor al deze functies veroorzaakt enige overhead voor prestaties. Broncodegeneratie kan de serialisatieprestaties verbeteren door geoptimaliseerde code te genereren die Utf8JsonWriter rechtstreeks gebruikt.

De serialisatie-optimalisatiemodus verzendt snelle serialisatiemethoden, maar geen serialisatiemetagegevens. Snelpadserialisatie is beperkt in wat het kan doen; het biedt geen ondersteuning voor asynchrone serialisatie of een modus voor deserialisatie.

Bovendien biedt de geoptimaliseerde code 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 welke opties in JsonSerializerOptions worden ondersteund door snelpad-serialisatie.

Serialisatieoptie Ondersteund voor snelle route
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 snelle route
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 deze 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 metagegevensmodus. Als u alleen de serialisatieoptimalisatiemodus selecteert, kan serialisatie mislukken voor typen of opties die terug moeten vallen op JsonSerializer code.

Zie ook

  • Laatst bijgewerkt om