Sdílet prostřednictvím

Požadované vlastnosti

  • Článek

Můžete označit určité vlastnosti, které značí, že musí být k dispozici v datové části JSON, aby bylo možné provést deserializaci. Podobně můžete nastavit možnost, která určuje, že všechny parametry konstruktoru, které nejsou volitelné, se nacházejí v datové části JSON. Pokud některé z těchto požadovaných vlastností nejsou přítomny JsonSerializer.Deserialize , metody vyvolá výjimku JsonException.

Existují tři způsoby, jak označit vlastnost nebo pole jako povinné pro deserializaci JSON:

Chcete-li určit, že všechny nepovinné parametry konstruktoru jsou vyžadovány pro deserializaci JSON, nastavte JsonSerializerOptions.RespectRequiredConstructorParameters možnost (nebo pro generování zdroje, RespectRequiredConstructorParameters vlastnost) na truehodnotu . Další informace naleznete v oddílu Nepovinný konstruktor parametry .

Z pohledu serializátoru jsou modifikátor a [JsonRequired] atribut jazyka C# required ekvivalentní a oba mapují na stejnou část metadat, což je JsonPropertyInfo.IsRequired. Ve většině případů byste jednoduše použili integrované klíčové slovo jazyka C#. V následujících případech byste ale měli místo toho použít JsonRequiredAttribute :

  • Pokud používáte jiný programovací jazyk než C# nebo nižší verzi jazyka C#.
  • Pokud chcete, aby se požadavek použil pouze na deserializaci JSON.
  • Pokud používáte System.Text.Json serializaci v režimu generování zdroje. V takovém případě se váš kód nezkompiluje, pokud použijete required modifikátor, protože generování zdroje probíhá v době kompilace.

Následující fragment kódu ukazuje příklad vlastnosti upravené klíčovým slovem required . Tato vlastnost musí být k dispozici v datové části JSON, aby bylo možné provést deserializaci.

public static void RunIt()
{
    // The following line throws a JsonException at run time.
    Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
}

public class Person
{
    public required string Name { get; set; }
    public int Age { get; set; }
}

Alternativně můžete použít JsonRequiredAttribute:

public static void RunIt()
{
    // The following line throws a JsonException at run time.
    Console.WriteLine(JsonSerializer.Deserialize<Person>("""{"Age": 42}"""));
}

public class Person
{
    [JsonRequired]
    public string Name { get; set; }
    public int Age { get; set; }
}

Pomocí vlastnosti je také možné určit, jestli se vlastnost vyžaduje prostřednictvím modelu kontraktu JsonPropertyInfo.IsRequired :

public static void RunIt()
{
    var options = new JsonSerializerOptions
    {
        TypeInfoResolver = new DefaultJsonTypeInfoResolver
        {
            Modifiers =
            {
                static typeInfo =>
                {
                    if (typeInfo.Kind != JsonTypeInfoKind.Object)
                        return;

                    foreach (JsonPropertyInfo propertyInfo in typeInfo.Properties)
                    {
                        // Strip IsRequired constraint from every property.
                        propertyInfo.IsRequired = false;
                    }
                }
            }
        }
    };

    // Deserialization succeeds even though
    // the Name property isn't in the JSON payload.
    JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);
}

public class Person
{
    public required string Name { get; set; }
    public int Age { get; set; }
}

Nepovinné parametry konstruktoru

Před rozhraním .NET 9 se deserializace založená na konstruktoru zacházelo se všemi parametry konstruktoru jako volitelné, jak ukazuje následující příklad:

var result = JsonSerializer.Deserialize<Person>("{}");
Console.WriteLine(result); // Person { Name = , Age = 0 }

record Person(string Name, int Age);

Počínaje rozhraním .NET 9 můžete příznak nastavit RespectRequiredConstructorParameters tak, aby podle potřeby zpracovával parametry konstruktoru, které nejsou volitelné.

public static void RunIt()
{
    JsonSerializerOptions options = new()
    {
        RespectRequiredConstructorParameters = true
    };
    string json = """{"Age": 42}""";

    // The following line throws a JsonException at run time.
    JsonSerializer.Deserialize<Person>(json, options);
}

record Person(string Name, int? Age = null);

Přepínač funkce

Nastavení můžete zapnout RespectRequiredConstructorParameters globálně pomocí System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault přepínače funkcí. Do souboru projektu přidejte následující položku MSBuild (například soubor .csproj ):

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

Rozhraní RespectRequiredConstructorParametersDefault API bylo implementováno jako příznak výslovného souhlasu v .NET 9, aby nedocházelo k přerušení stávajících aplikací. Pokud píšete novou aplikaci, důrazně doporučujeme povolit tento příznak ve svém kódu.

Viz také