Condividi tramite

Proprietà obbligatorie

  • Articolo

È possibile contrassegnare determinate proprietà per indicare che devono essere presenti nel payload JSON affinché la deserializzazione abbia esito positivo. Analogamente, è possibile impostare un'opzione per specificare che tutti i parametri del costruttore non facoltativi sono presenti nel payload JSON. 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:

Per specificare che tutti i parametri del costruttore non facoltativi sono necessari per la deserializzazione JSON, impostare l'opzione JsonSerializerOptions.RespectRequiredConstructorParameters (o, per la generazione di origine, RespectRequiredConstructorParameters la proprietà) su true. Per altre informazioni, vedere la sezione Parametri del costruttore non facoltativo .

Dal punto di vista del serializzatore, il modificatore e [JsonRequired] l'attributo C# required sono equivalenti ed entrambi eseguono 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.

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

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

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

Parametri del costruttore non facoltativi

Prima di .NET 9, la deserializzazione basata su costruttore considerava facoltativi tutti i parametri del costruttore, come illustrato nell'esempio seguente:

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

record Person(string Name, int Age);

A partire da .NET 9, è possibile impostare il RespectRequiredConstructorParameters flag per considerare i parametri del costruttore non facoltativi in base alle esigenze.

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

Cambio di funzionalità

È possibile attivare l'impostazione a livello globale usando l'opzione RespectRequiredConstructorParameters di System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault funzionalità. Aggiungere l'elemento MSBuild seguente al file di progetto (ad esempio, file con estensione csproj ):

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

L'API RespectRequiredConstructorParametersDefault è stata implementata come flag di consenso esplicito in .NET 9 per evitare l'interruzione delle applicazioni esistenti. Se si sta scrivendo una nuova applicazione, è consigliabile abilitare questo flag nel codice.

Vedi anche