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

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 modulu runtime 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 modulu runtime, 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.

Neveřejné členy a konstruktory

Ve výchozím nastavení zahrnují režim reflexe i režim generování zdroje pouze public vlastnosti a pole ve smlouvě serializace.

Od .NET 11 podporuje generování zdroje členy, které explicitně označíte atributem [JsonInclude]. Člen může být private, internalnebo protected. Podporuje také private, internala protected přístupové objekty u vlastností, které označíte znakem [JsonInclude]. Generování zdroje také podporuje nepřístupné konstruktory označené [JsonConstructor].

Na .NET 11 se generované přístupové objekty používají UnsafeAccessorAttribute.

Zdrojově generovaný setter pro vlastnost pouze pro init se spustí pouze tehdy, když datová část ve formátu JSON obsahuje tuto vlastnost. Vlastnost typu init-only, kterou datová část neobsahuje, si ponechá hodnotu ze svého inicializátoru.

V .NET 10 a starších verzích má generování zdroje následující omezení:

  • Generování zdrojového kódu nepodporuje členy ani přístupové metody private nebo protected. Pokud takový člen označíte jako , [JsonInclude]serializátor vyvolá NotSupportedException za běhu.
  • Generování zdroje podporuje internal členy a přístupové objekty pouze tehdy, když jsou přístupné pro vygenerované JsonSerializerContext ve stejném sestavení.
  • Generování zdroje nepodporuje konstruktory, které jsou nepřístupné pro vygenerovaný kontext, i když je označíte pomocí [JsonConstructor].

Známé problémy

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é umožňují přizpůsobení výstupu serializace, například zásady pojmenovává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.

Režim optimalizace serializace generuje rychlé metody serializace, ale nikoli metadata serializace. Serializace fast-path je omezena v tom, co může dělat; nepodporuje asynchronní serializaci ani žádný režim deserializace.

Optimalizovaný kód navíc 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é možnosti v JsonSerializerOptions jsou podporovány rychlou serializací:

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 se použít 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 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é

  • Poslední aktualizace v