Erforderliche Eigenschaften

  • Artikel

Sie können bestimmte Eigenschaften markieren, um anzugeben, dass sie in den JSON-Nutzdaten vorhanden sein müssen, damit die Deserialisierung erfolgreich ist. Sie können ebenso eine Option festlegen, um anzugeben, dass alle nicht optionalen Konstruktorparameter in der JSON-Nutzlast vorhanden sind. Wenn mindestens eine dieser erforderlichen Eigenschaften nicht vorhanden ist, lösen die JsonSerializer.Deserialize-Methoden eine JsonException aus.

Es gibt drei Möglichkeiten, eine Eigenschaft oder ein Feld als erforderlich für die JSON-Deserialisierung zu markieren:

Um anzugeben, dass alle nicht optionalen Konstruktorparameter für die JSON-Deserialisierung erforderlich sind, legen Sie die Option JsonSerializerOptions.RespectRequiredConstructorParameters (oder, für die Quellgenerierung die Eigenschaft RespectRequiredConstructorParameters) auf true fest. Weitere Informationen finden Sie im Abschnitt Nicht optionale Konstruktorparameter.

Aus der Perspektive des Serialisierungsprogramms sind der C# required-Modifizierer und das [JsonRequired]-Attribut gleichwertig, und beide werden denselben Metadaten zugeordnet, d h. JsonPropertyInfo.IsRequired. In den meisten Fällen verwenden Sie einfach das integrierte C#-Schlüsselwort. In den folgenden Fällen sollten Sie stattdessen jedoch JsonRequiredAttribute verwenden:

  • Wenn Sie eine andere Programmiersprache als C# oder eine untergeordnete Version von C# verwenden.
  • Wenn Sie möchten, dass die Anforderung nur auf die JSON-Deserialisierung angewendet werden soll.
  • Wenn Sie die System.Text.Json-Serialisierung im Quellgenerierungsmodus verwenden. In diesem Fall lässt sich Ihr Code nicht kompilieren, wenn Sie den required-Modifizierer verwenden, da die Quellgenerierung zur Kompilierzeit erfolgt.

Das folgende Codeschnipsel zeigt ein Beispiel für eine Eigenschaft, die mit dem Schlüsselwort required geändert wurde. Diese Eigenschaft muss in den JSON-Nutzdaten vorhanden sein, damit die Deserialisierung erfolgreich ist.

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

Alternativ kannst du auch JsonRequiredAttribute verwenden:

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

Ferner kann auch über das Vertragsmodell unter Verwendung der Eigenschaft JsonPropertyInfo.IsRequired gesteuert werden, ob eine Eigenschaft erforderlich ist:

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

Nicht optionale Konstruktorparameter

Vor .NET 9 behandelte die konstruktorbasierte Deserialisierung alle Konstruktorparameter als optional, wie im folgenden Beispiel gezeigt:

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

record Person(string Name, int Age);

Ab .NET 9 können Sie das RespectRequiredConstructorParameters-Flag so festlegen, dass nicht optionale Konstruktorparameter wie erforderlich behandelt werden.

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

Funktionsschalter

Sie können die Einstellung RespectRequiredConstructorParameters mithilfe des Funktionsschalters System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault aktivieren. Fügen Sie der Projektdatei das folgende MSBuild-Element hinzu (z. B. .csproj-Datei):

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

Die RespectRequiredConstructorParametersDefault-API wurde als Opt-In-Flag in .NET 9 implementiert, um zu vermeiden, dass vorhandene Anwendungen unterbrochen werden. Wenn Sie eine neue Anwendung schreiben, wird dringend empfohlen, dieses Flag in Ihrem Code zu aktivieren.

Siehe auch