Modalità di generazione dell'origine in System.Text.Json

  • Articolo

La generazione di origine può essere usata in due modalità: Ottimizzazione della serializzazione e basata su metadati. Questo articolo descrive le diverse modalità.

Per informazioni su come usare le modalità di generazione di origine, vedere Come usare la generazione di origine in System.Text.Json.

Modalità basata su metadati

È possibile usare la generazione di origine per spostare il processo di raccolta dei metadati dal runtime al tempo di compilazione. Durante la compilazione, i metadati vengono raccolti e vengono generati i file di codice sorgente. I file di codice sorgente generati vengono compilati automaticamente come parte integrante dell'applicazione. Questa tecnica elimina la raccolta di metadati in fase di esecuzione, migliorando le prestazioni della serializzazione e della deserializzazione.

I miglioramenti delle prestazioni offerti dalla generazione di origine possono essere sostanziali. Ad esempio, i risultati dei test hanno mostrato fino al 40% o più riduzione del tempo di avvio, riduzione della memoria privata, aumento della velocità effettiva (in modalità di ottimizzazione della serializzazione) e riduzione delle dimensioni dell'app.

Problemi noti

Solo public le proprietà e i campi sono supportati per impostazione predefinita in modalità di serializzazione. Tuttavia, la modalità reflection supporta l'uso delle funzioni di privateaccesso, mentre la modalità di generazione dell'origine non è attiva. Ad esempio, è possibile applicare l'attributo JsonInclude a una proprietà con un private setter o un getter e che verrà serializzata in modalità reflection. La modalità di generazione dell'origine supporta solo public le funzioni di accesso o internal le funzioni di accesso delle public proprietà. Se si impostano [JsonInclude] funzioni di accesso non pubbliche e si sceglie la modalità di generazione dell'origine, verrà generata un'eccezione NotSupportedException in fase di esecuzione.

Solo public le proprietà e i campi sono supportati per impostazione predefinita in modalità di serializzazione. Tuttavia, la modalità reflection supporta l'uso di membri e privatefunzioni di private accesso, mentre la modalità di generazione dell'origine non è attiva. Ad esempio, se si applica l'attributo JsonInclude a una private proprietà o a una proprietà con un private setter o getter, verrà serializzato in modalità reflection. La modalità di generazione dell'origine supporta solo public membri o internal funzioni di accesso o publicinternal di public proprietà. Se si impostano [JsonInclude]private su membri o funzioni di accesso e si sceglie la modalità di generazione dell'origine, verrà generata un'eccezione NotSupportedException in fase di esecuzione.

Per informazioni su altri problemi noti relativi alla generazione dell'origine, vedere i problemi di GitHub etichettati come "generatore di origine" nel repository dotnet/runtime .

Modalità Ottimizzazione della serializzazione (percorso rapido)

JsonSerializer include molte funzionalità che personalizzano l'output della serializzazione, ad esempio i criteri di denominazione e conservano i riferimenti. Il supporto per tutte queste funzionalità causa un sovraccarico delle prestazioni. La generazione di origine può migliorare le prestazioni di serializzazione generando codice ottimizzato che usa Utf8JsonWriter direttamente.

Il codice ottimizzato non supporta tutte le funzionalità di serializzazione supportate JsonSerializer . Il serializzatore rileva se il codice ottimizzato può essere usato ed esegue il fallback al codice di serializzazione predefinito se vengono specificate opzioni non supportate. Ad esempio, JsonNumberHandling.AllowReadingFromString non è applicabile alla scrittura, quindi la specifica di questa opzione non causa un fallback al codice predefinito.

La tabella seguente illustra le opzioni in JsonSerializerOptions supportate dalla serializzazione fast-path:

Opzione di serializzazione Supportato per fast-path
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

Le opzioni seguenti non sono supportate perché si applicano solo alla deserializzazione: PropertyNameCaseInsensitive, ReadCommentHandlinge UnknownTypeHandling.

La tabella seguente illustra gli attributi supportati dalla serializzazione fast-path:

Attributo Supportato per fast-path
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

Se per un tipo viene specificata un'opzione o un attributo non supportato, il serializzatore esegue il fallback alla modalità metadati, presupponendo che il generatore di origine sia stato configurato per generare metadati. In tal caso, il codice ottimizzato non viene usato durante la serializzazione di tale tipo, ma può essere usato per altri tipi. È quindi importante eseguire test delle prestazioni con le opzioni e i carichi di lavoro per determinare il vantaggio che è effettivamente possibile ottenere dalla modalità di ottimizzazione della serializzazione. Inoltre, la possibilità di eseguire il fallback al JsonSerializer codice richiede la modalità di raccolta dei metadati. Se si seleziona solo la modalità di ottimizzazione della serializzazione, la serializzazione potrebbe non riuscire per tipi o opzioni che devono eseguire il fallback al JsonSerializer codice.

Vedi anche