System.Text.Json forrásgenerátor visszaállás

Amikor a JsonSerializer-t elfogadó JsonSerializerOptions metódusok egyikét használjuk, a System.Text.Json forrásgenerátor többé nem fog implicit módon visszaesni a nem felismert típusok tükröződésalapú szerializálására.

Előző viselkedés

Tekintse meg a következő forrásgenerálási példát a .NET 6-ban:

JsonSerializer.Serialize(new Poco2(), typeof(Poco2), MyContext.Default);

[JsonSerializable(typeof(Poco1))]
public partial class MyContext : JsonSerializerContext {}

public class Poco1 { }
public class Poco2 { }

Mivel MyContext nem tartalmazza Poco2 a szerializálható típusok között, a szerializálás a következő kivétellel megfelelően meghiúsul:

System.InvalidOperationException:

'Metadata for type 'Poco2' was not provided to the serializer. The serializer method used does not
support reflection-based creation of serialization-related type metadata. If using source generation,
ensure that all root types passed to the serializer have been indicated with 'JsonSerializableAttribute',
along with any types that might be serialized polymorphically.

Most vegye figyelembe a következő hívást, amely megpróbálja szerializálni ugyanazt a típust (MyContext) a JsonSerializerOptions forrásgenerátor által létrehozott példány használatával:

JsonSerializer.Serialize(new Poco2(), MyContext.Default.Options);

A beállításpéldány csendesen belefoglalja az alapértelmezett tükröződésalapú szerződésfeloldót tartalék mechanizmusként, és mint ilyen, a típus sikeresen szerializál – a tükröződés használatával.

Ugyanez a tartalék logika vonatkozik az opció példányaira, amelyek csatlakoznak egy JsonSerializerOptions.GetConverter(Type)-hez. A következő utasítás egy konvertert ad vissza a beépített tükröződéskonverter használatával:

JsonConverter converter = MyContext.Default.Options.GetConverter(typeof(Poco2));

Új viselkedés

A .NET 7-től kezdve a következő hívás ugyanazzal a kivétellel (InvalidOperationException) meghiúsul, mint a JsonSerializerContext túlterhelés használatakor:

JsonSerializer.Serialize(new Poco2(), MyContext.Default.Options);

Ezenkívül a következő utasítás sikertelen lesz a következővel NotSupportedException:

JsonConverter converter = MyContext.Default.Options.GetConverter(typeof(Poco2));

Bevezetett verzió

.NET 7

A kompatibilitástörő változás típusa

Ez a változás befolyásolhatja a bináris kompatibilitást.

A változás oka

Az előző viselkedés sérti a legkisebb meglepetés elvét, és végső soron legyőzi a forrásgenerálás célját. Egy olyan funkció kiadásával, amely lehetővé teszi a típusok JSON szerializálási szerződéseinek testreszabását, finomhangolhatja a szerződés metaadatainak forrásait. Ezt szem előtt tartva az alternatív források csendes bevezetése még kevésbé lesz kívánatos.

Javasolt művelet

Az előző viselkedéstől függhet, akár szándékosan, akár akaratlanul. Az ajánlott eljárás a definíció frissítése JsonSerializerContext, hogy az tartalmazza az összes típusfüggőséget.

[JsonSerializable(typeof(Poco1))]
[JsonSerializable(typeof(Poco2))]
public partial class MyContext : JsonSerializerContext {}

Ez lehetővé teszi, hogy az alkalmazás teljes mértékben kihasználja a forrásgenerálás előnyeit, beleértve a vágásbiztonságot is.

Bizonyos esetekben azonban előfordulhat, hogy az ilyen módosítás végrehajtása nem praktikus vagy lehetséges. Annak ellenére, hogy nem ajánlott, a forrás által létrehozott szerializálóban kétféleképpen is újra engedélyezheti a visszatükrözést.

Egyéni szerződésfeloldó használata

Az új szerződés-testreszabási funkcióval létrehozhat egy egyéni szerződésfeloldót, amely szükség esetén visszaesik a tükröződésalapú megoldásra:

var options = new JsonSerializerOptions
{
     TypeInfoResolver = JsonTypeInfoResolver.Combine(MyContext.Default, new DefaultJsonTypeInfoResolver());
}

JsonSerializer.Serialize(new Poco2(), options); // Contract resolution falls back to the default reflection-based resolver.
options.GetConverter(typeof(Poco2)); // Returns the reflection-based converter.

AppContext kapcsoló használata

A .NET 7-től kezdve globálisan újra engedélyezheti a reflection visszaesését a megadott AppContext kompatibilitási kapcsolóval. Adja hozzá az alábbi bejegyzést az alkalmazás projektfájljához, hogy újra engedélyezze a reflexiós visszaesést az alkalmazás összes forrás által generált kontextusánál. Az AppContext-kapcsolók használatáról további információt a .NET futtatókörnyezet konfigurációs beállításairól szóló cikkben talál.

<ItemGroup>
  <RuntimeHostConfigurationOption Include="System.Text.Json.Serialization.EnableSourceGenReflectionFallback" Value="true" />
</ItemGroup>

Érintett API-k

• System.Text.Json.JsonSerializerOptions.GetConverter(Type)
• System.Text.Json.JsonSerializer.Serialize(Stream, Object, Type, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.Serialize(Object, Type, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.Serialize(Utf8JsonWriter, Object, Type, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.Serialize<TValue>(TValue, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.Serialize<TValue>(Stream, TValue, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.Serialize<TValue>(Utf8JsonWriter, TValue, JsonSerializerOptions)
• System.Text.Json.JsonSerializer.SerializeAsync(Stream, Object, Type, JsonSerializerOptions, CancellationToken)
• System.Text.Json.JsonSerializer.SerializeAsync<TValue>(Stream, TValue, JsonSerializerOptions, CancellationToken)