Erforderliche Eigenschaften
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:
- Durch Hinzufügen des
required
-Modifizierers. - Durch Kommentieren mit JsonRequiredAttribute.
- Durch Ändern der JsonPropertyInfo.IsRequired-Eigenschaft des Vertragsmodells.
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 denrequired
-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.