Källgenereringslägen i System.Text.Json

Källgenerering kan användas i två lägen: metadatabaserad och serialiseringsoptimering. I den här artikeln beskrivs de olika lägena.

Information om hur du använder källgenereringslägen finns i Så här använder du källgenerering i System.Text.Json.

Metadatabaserat läge

Du kan använda källgenerering för att flytta processen för metadatainsamling från körning till kompileringstid. Under kompilering samlas metadata in och källkodsfiler genereras. De genererade källkodsfilerna kompileras automatiskt som en integrerad del av programmet. Den här tekniken eliminerar insamling av runtime-metadata, vilket förbättrar prestanda för både serialisering och deserialisering.

Prestandaförbättringarna som tillhandahålls av källgenereringen kan vara betydande. Testresultat har till exempel visat upp till 40 % eller mer minskning av starttiden, minskning av privat minne, ökning av dataflödeshastigheten (i serialiseringsoptimeringsläge) och minskning av appstorleken.

Icke-offentliga medlemmar och konstruktorer

Som standard innehåller både reflektionsläget och källgenereringsläget endast public egenskaper och fält i serialiseringskontraktet.

Från och med .NET 11 har källgenereringen stöd för medlemmar som du uttryckligen markerar med attributet [JsonInclude]. Medlemmen kan vara private, internaleller protected. Den stöder också private, internal och protected åtkomstfunktioner för egenskaper som markeras med [JsonInclude]. Källgenereringen stöder också otillgängliga konstruktorer markerade med [JsonConstructor].

I .NET 11 använder de genererade åtkomstmetoderna UnsafeAccessorAttribute.

En källgenererad setter för en init-only-egenskap körs endast när JSON-nyttolasten innehåller den egenskapen. En init-only-egenskap som nyttolasten utelämnar behåller värdet från dess egenskapsinitierare.

I .NET 10 och tidigare versioner har källgenereringen följande begränsningar:

• Källgenerering stöder varken private eller protected medlemmar eller åtkomstfunktioner. Om du markerar en sådan medlem med [JsonInclude], kastar serialiseraren en NotSupportedException under körning.
• Källgenerering stöder endast internal-medlemmar och åtkomstmetoder när de är tillgängliga för den genererade JsonSerializerContext i samma sammansättning.
• Källgenereringen stöder inte konstruktorer som inte är tillgängliga för den genererade kontexten, även när du markerar dem med [JsonConstructor].

Kända problem

Information om andra kända problem med källgenerering finns i GitHub-problem som är märkta med "källgenerator" på dotnet/runtime-lagringsplatsen .

Serialiseringsoptimeringsläge (snabb sökväg)

JsonSerializer har många funktioner som anpassar utdata från serialisering, till exempel namngivningsprinciper och bevarande av referenser. Stöd för alla dessa funktioner orsakar vissa prestandakostnader. Källgenerering kan förbättra serialiseringsprestanda genom att generera optimerad kod som använder Utf8JsonWriter direkt.

Serialiseringsoptimeringsläget genererar snabbare serialiseringsmetoder men inte serialiseringsmetadata. Fast-path serialisering är begränsad i vad den kan göra. Den stöder inte asynkron serialisering eller någon form av deserialisering.

Dessutom stöder den optimerade koden inte alla serialiseringsfunktioner som JsonSerializer stöds. Serialiseraren identifierar om den optimerade koden kan användas och återgår till standardserielliseringskoden om alternativ som inte stöds har angetts. Det är till exempel JsonNumberHandling.AllowReadingFromString inte tillämpligt när det gäller att skriva kod, så att ange det här alternativet leder inte till att det faller tillbaka till en standardkod.

I följande tabell visas vilka alternativ i JsonSerializerOptions som stöds av snabbspår-serialisering:

(Följande alternativ stöds inte eftersom de endast gäller för deserialisering: PropertyNameCaseInsensitive, ReadCommentHandling, och UnknownTypeHandling.)

I följande tabell visas vilka attribut som stöds av serialisering med snabbväg:

Om ett alternativ eller attribut som inte stöds anges för en typ återgår serialiseraren till metadataläge, förutsatt att källgeneratorn har konfigurerats för att generera metadata. I så fall används inte den optimerade koden vid serialisering av den typen, men den kan användas för andra typer. Därför är det viktigt att utföra prestandatestning med dina alternativ och arbetsbelastningar för att avgöra hur stor nytta du faktiskt kan få av serialiseringsoptimeringsläget. Möjligheten att återgå till JsonSerializer kod kräver också metadataläge. Om du bara väljer serialiseringsoptimeringsläge kan serialiseringen misslyckas för typer eller alternativ som måste återgå till JsonSerializer koden.

Se även

• JSON-serialisering och deserialisering i .NET – översikt
• Så här använder du biblioteket