Partager via

Propriétés requises

  • Article

Vous pouvez marquer certaines propriétés pour indiquer qu’elles doivent être présentes dans la charge JSON pour que la désérialisation réussisse. De même, vous pouvez définir une option pour spécifier que tous les paramètres de constructeur non optionnels sont présents dans la charge JSON. 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 :

Pour spécifier que tous les paramètres de constructeur non optionnels sont requis pour la désérialisation JSON, définissez l’option JsonSerializerOptions.RespectRequiredConstructorParameters (ou, pour la génération de code source, la propriété RespectRequiredConstructorParameters) sur true. Pour plus d’informations, consultez la section Paramètres de constructeur non optionnels.

Du point de vue du sérialiseur, le modificateur C# required et l’attribut [JsonRequired] sont équivalents et mappent tous deux 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.

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

Vous pouvez également utiliser 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; }
}

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 :

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

Paramètres de constructeur non optionnels

Avant .NET 9, la désérialisation basée sur le constructeur traitait tous les paramètres du constructeur comme optionnels, comme le montre l’exemple suivant :

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

record Person(string Name, int Age);

À partir de .NET 9, vous pouvez définir l’indicateur RespectRequiredConstructorParameters pour traiter les paramètres de constructeur non optionnels comme requis.

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

Commutateur de fonctionnalité

Vous pouvez activer l’option RespectRequiredConstructorParameters globalement en utilisant le commutateur de fonctionnalité System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault. Ajoutez l’élément MSBuild suivant à votre fichier de projet (par exemple, le fichier .csproj) :

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

L’API RespectRequiredConstructorParametersDefault a été implémentée comme un indicateur activable dans .NET 9 pour éviter de rompre les applications existantes. Si vous écrivez une nouvelle application, il est fortement recommandé d’activer cet indicateur dans votre code.

Voir aussi