Udostępnij za pośrednictwem

Wymagane właściwości

  • Artykuł

Aby oznaczyć pewne właściwości, można oznaczyć, że muszą one znajdować się w ładunku JSON, aby deserializacja zakończyła się pomyślnie. Podobnie można ustawić opcję, aby określić, że wszystkie parametry konstruktora inne niż opcjonalne znajdują się w ładunku JSON. Jeśli co najmniej jedna z tych wymaganych właściwości nie jest obecna, JsonSerializer.Deserialize metody zgłaszają JsonExceptionwartość .

Istnieją trzy sposoby oznaczania właściwości lub pola zgodnie z wymaganiami deserializacji JSON:

Aby określić, że do deserializacji JSON są wymagane wszystkie parametry konstruktora innego niż opcjonalny, ustaw JsonSerializerOptions.RespectRequiredConstructorParameters opcję (lub dla generowania źródła, RespectRequiredConstructorParameters właściwość) na truewartość . Aby uzyskać więcej informacji, zobacz sekcję Parametry konstruktora nie opcjonalnego.

Z perspektywy serializatora modyfikator języka C# required i [JsonRequired] atrybut są równoważne, a oba elementy są mapowane na ten sam element metadanych, czyli JsonPropertyInfo.IsRequired. W większości przypadków wystarczy użyć wbudowanego słowa kluczowego języka C#. Jednak w następujących przypadkach należy użyć zamiast JsonRequiredAttribute tego:

  • Jeśli używasz języka programowania innego niż C# lub starszej wersji języka C#.
  • Jeśli chcesz zastosować tylko wymaganie dotyczące deserializacji JSON.
  • Jeśli używasz System.Text.Json serializacji w trybie generowania źródła. W takim przypadku kod nie zostanie skompilowany, jeśli używasz required modyfikatora, ponieważ generowanie źródła występuje w czasie kompilacji.

Poniższy fragment kodu przedstawia przykład właściwości zmodyfikowanej za pomocą słowa kluczowego required . Ta właściwość musi znajdować się w ładunku JSON, aby deserializacja powiodła się.

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; }
}

Alternatywnie możesz użyć polecenia 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; }
}

Istnieje również możliwość kontrolowania, czy właściwość jest wymagana za pośrednictwem modelu kontraktu JsonPropertyInfo.IsRequired przy użyciu właściwości :

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; }
}

Parametry konstruktora innego niż opcjonalny

Przed platformą .NET 9 deserializacja oparta na konstruktorach potraktowała wszystkie parametry konstruktora jako opcjonalne, jak pokazano w poniższym przykładzie:

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

record Person(string Name, int Age);

Począwszy od platformy .NET 9, można ustawić flagę RespectRequiredConstructorParameters tak, aby traktować parametry konstruktora inne niż opcjonalne zgodnie z potrzebami.

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);

Przełączniki funkcji

Ustawienie można włączyć RespectRequiredConstructorParameters globalnie przy użyciu przełącznika System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault funkcji. Dodaj następujący element MSBuild do pliku projektu (na przykład plik csproj ):

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

Interfejs API został zaimplementowany jako flaga RespectRequiredConstructorParametersDefault zgody na platformie .NET 9, aby uniknąć przerywania istniejących aplikacji. Jeśli piszesz nową aplikację, zdecydowanie zaleca się włączenie tej flagi w kodzie.

Zobacz też