Proprietà obbligatorie

A partire da .NET 7, è possibile contrassegnare determinate proprietà per indicare che devono essere presenti nel payload JSON per consentire una corretta deserializzazione. Se una o più di queste proprietà obbligatorie non sono presenti, i metodi JsonSerializer.Deserialize generano un'eccezione JsonException.

Esistono tre modi per contrassegnare una proprietà o un campo come obbligatorio per la deserializzazione JSON:

• Aggiungendo il modificatore required, che è una novità di C# 11.
• Aggiungendo l'annotazione JsonRequiredAttribute, che è una novità di .NET 7.
• Modificando la proprietà JsonPropertyInfo.IsRequired del modello di contratto, che è una novità di .NET 7.

Dal punto di vista del serializzatore, queste due demarcazioni sono equivalenti ed entrambe consentono di eseguire il mapping allo stesso frammento di metadati, ovvero JsonPropertyInfo.IsRequired. Nella maggior parte dei casi è sufficiente usare la parola chiave C# predefinita. Tuttavia, è consigliabile usare JsonRequiredAttribute nei casi seguenti:

• Se si usa un linguaggio di programmazione diverso da C# o una versione inferiore di C#.
• Se si vuole applicare solo il requisito alla deserializzazione JSON.
• Se si usa la serializzazione System.Text.Json in modalità di generazione dell'origine. In questo caso, il codice non verrà compilato se si usa il modificatore required, perché la generazione dell'origine avviene in fase di compilazione.

Il frammento di codice seguente mostra un esempio di una proprietà modificata con la parola chiave required. Questa proprietà deve essere presente nel payload JSON per consentire una corretta deserializzazione.

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

In alternativa, è possibile usare 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; }
}

È anche possibile controllare se una proprietà è obbligatoria tramite il modello di contratto usando la proprietà 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);