Sdílet prostřednictvím

Režimy zdrojové generace v System.Text.Json

  • Článek

Generování zdroje lze použít ve dvou režimech: optimalizace na základě metadat a serializace. Tento článek popisuje různé režimy.

Informace o tom, jak používat režimy generování zdrojů, naleznete v tématu Jak používat generování zdroje v System.Text.Json.

Režim založený na metadatech

Pomocí generování zdroje můžete přesunout proces shromažďování metadat z doby běhu do doby kompilace. Během kompilace se shromažďují metadata a generují se soubory zdrojového kódu. Vygenerované soubory zdrojového kódu se automaticky kompilují jako nedílnou součást aplikace. Tato technika eliminuje shromažďování metadat za běhu, což zlepšuje výkon serializace i deserializace.

Vylepšení výkonu poskytované generováním zdrojů můžou být podstatná. Například výsledky testů ukázaly až 40 % nebo více zkrácení doby spuštění, snížení velikosti privátní paměti, zvýšení rychlosti propustnosti (v režimu optimalizace serializace) a zmenšení velikosti aplikace.

Známé problémy

V režimu serializace jsou ve výchozím nastavení podporovány pouze public vlastnosti a pole. Režim reflexe ale podporuje použití přístupových private objektů, zatímco režim generování zdroje není. Například můžete použít JsonInclude atribut na vlastnost, která má private setter nebo getter a bude serializována v režimu reflexe. Režim generování zdroje podporuje pouze public vlastnosti nebo internal přístupové objekty public . Pokud nastavíte neveřejné přístupové objekty a zvolíte [JsonInclude] režim generování zdroje, NotSupportedException vyvolá se za běhu.

V režimu serializace jsou ve výchozím nastavení podporovány pouze public vlastnosti a pole. Režim reflexe ale podporuje použití členů a private přístupových privateobjektů, zatímco režim generování zdroje není. Pokud například použijete atribut JsonInclude na private vlastnost nebo vlastnost, která má private setter nebo getter, bude serializována v režimu reflexe. Režim generování zdroje podporuje pouze public internal členy a public přístupové internal objekty public vlastností. Pokud nastavíte členy nebo přístupové objekty a zvolíte [JsonInclude] private režim generování zdroje, NotSupportedException vyvolá se za běhu.

Informace o dalších známých problémech s generováním zdroje najdete v problémech GitHubu, které jsou označené jako source-generator v úložišti dotnet/runtime .

Režim optimalizace serializace (rychlá cesta)

JsonSerializer má mnoho funkcí, které přizpůsobí výstup serializace, jako jsou zásady pojmenování a zachování odkazů. Podpora všech těchto funkcí způsobuje určité režijní náklady na výkon. Generování zdroje může zlepšit výkon serializace generováním optimalizovaného kódu, který používá Utf8JsonWriter přímo.

Optimalizovaný kód nepodporuje všechny funkce serializace, které JsonSerializer podporují. Serializátor zjistí, jestli je možné použít optimalizovaný kód, a pokud jsou zadány nepodporované možnosti, vrátí se zpět do výchozího kódu serializace. Například JsonNumberHandling.AllowReadingFromString se nedá použít pro zápis, takže zadání této možnosti nezpůsobí náhradní použití výchozího kódu.

Následující tabulka ukazuje, které JsonSerializerOptions možnosti jsou podporovány serializací rychlých cest:

Možnost serializace Podporováno pro rychlou cestu
AllowTrailingCommas ✔️
Converters ❌
DefaultBufferSize ✔️
DefaultIgnoreCondition ✔️
DictionaryKeyPolicy ❌
Encoder ❌
IgnoreNullValues ❌
IgnoreReadOnlyFields ✔️
IgnoreReadOnlyProperties ✔️
IncludeFields ✔️
MaxDepth ✔️
NumberHandling ❌
PropertyNamingPolicy ✔️
ReferenceHandler ❌
TypeInfoResolver ✔️
WriteIndented ✔️

(Následující možnosti nejsou podporovány, protože se vztahují pouze na deserializaci: PropertyNameCaseInsensitive, ReadCommentHandlinga UnknownTypeHandling.)

Následující tabulka ukazuje, které atributy jsou podporovány serializací fast-path:

Atribut Podporováno pro rychlou cestu
JsonConstructorAttribute ❌
JsonConverterAttribute ❌
JsonDerivedTypeAttribute ✔️
JsonExtensionDataAttribute ❌
JsonIgnoreAttribute ✔️
JsonIncludeAttribute ✔️
JsonNumberHandlingAttribute ❌
JsonPolymorphicAttribute ✔️
JsonPropertyNameAttribute ✔️
JsonPropertyOrderAttribute ✔️
JsonRequiredAttribute ✔️

Pokud je pro typ zadána nepodporovaná možnost nebo atribut, serializátor se vrátí do režimu metadat za předpokladu, že je generátor zdroje nakonfigurovaný tak, aby generoval metadata. V takovém případě se optimalizovaný kód nepoužívá při serializaci tohoto typu, ale může být použit pro jiné typy. Proto je důležité provádět testování výkonu s možnostmi a úlohami, abyste zjistili, kolik výhod můžete skutečně získat z režimu serializace-optimalizace. Možnost návratu do JsonSerializer kódu také vyžaduje režim shromažďování metadat. Pokud vyberete pouze režim optimalizace serializace, serializace může selhat pro typy nebo možnosti, které se musí vrátit do JsonSerializer kódu.

Viz také