Propriétés requises

À partir de .NET 7, vous pouvez marquer certaines propriétés pour indiquer qu’elles doivent être présentes dans la charge utile JSON pour que la désérialisation réussisse. Si une ou plusieurs de ces propriétés requises ne sont pas présentes, les méthodes JsonSerializer.Deserialize lèvent une exception JsonException.

Il existe trois façons de marquer une propriété ou un champ comme requis pour la désérialisation JSON :

• En ajoutant le modificateur requis, ce qui est nouveau dans C# 11.
• En l’annotant avec JsonRequiredAttribute, ce qui est nouveau dans .NET 7.
• En modifiant la propriété JsonPropertyInfo.IsRequired du modèle de contrat, ce qui est nouveau dans .NET 7.

Du point de vue du sérialiseur, ces deux démarcations sont équivalentes et toutes deux mappées au même élément de métadonnées, qui est JsonPropertyInfo.IsRequired. Dans la plupart des cas, vous utilisez simplement le mot clé C# intégré. Toutefois, dans les cas suivants, vous devez utiliser JsonRequiredAttribute à la place :

• Si vous utilisez un langage de programmation autre que C# ou une version de niveau inférieur de C#.
• Si vous souhaitez que la condition s’applique uniquement à la désérialisation JSON.
• Si vous utilisez la sérialisation System.Text.Json en mode génération de sources. Dans ce cas, votre code ne sera pas compilé si vous utilisez le modificateur, car la génération de sources required se produit au moment de la compilation.

L’extrait de code suivant montre un exemple de propriété modifiée avec le mot clé required. Cette propriété doit être présente dans la charge utile JSON pour que la désérialisation réussisse.

using System.Text.Json;

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

Vous pouvez également utiliser JsonRequiredAttribute :

using System.Text.Json;

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

Il est également possible de contrôler si une propriété est requise via le modèle de contrat à l’aide de la propriété JsonPropertyInfo.IsRequired :

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 now succeeds even though the Name property isn't in the JSON payload.
JsonSerializer.Deserialize<Person>("""{"Age": 42}""", options);