Comparteix a través de

Propiedades obligatorias

  • Article

Puede marcar ciertas propiedades para indicar que deben estar presentes en la carga de JSON para que la deserialización se realice correctamente. Del mismo modo, puede crear una opción para indicar que todos los parámetros de constructor no opcionales están presentes en la carga de JSON. Si una o varias de estas propiedades necesarias no están presentes, los métodos JsonSerializer.Deserialize inician una excepción JsonException.

Hay tres maneras de marcar una propiedad o un campo según proceda para la deserialización JSON:

Para indicar que todos los parámetros de constructor no opcionales son necesarios para la deserialización de JSON, cambie la opción JsonSerializerOptions.RespectRequiredConstructorParameters (o, para la generación de origen, la propiedad RespectRequiredConstructorParameters) a true. Para obtener más información, consulte la sección Parámetros de constructor no opcionales.

Desde la perspectiva del serializador, el modificador required de C# y el atributo [JsonRequired] son equivalentes y ambos se asignan al mismo fragmento de metadatos, que es JsonPropertyInfo.IsRequired. En la mayoría de los casos, simplemente usaría la palabra clave integrada de C#. Sin embargo, en los siguientes, debe usar JsonRequiredAttribute en su lugar:

  • Si usa un lenguaje de programación distinto de C# o una versión inferior de C#.
  • Si quiere que la obligación solo se aplique a la deserialización JSON.
  • Si usa la serialización System.Text.Json en modo de generación de origen. En este caso, el código no se compilará si usa el modificador required, ya que la generación de origen se produce en tiempo de compilación.

En el siguiente fragmento de código se muestra un ejemplo de una propiedad modificada con la palabra clave required. Esta propiedad debe estar presente en la carga de JSON para que la deserialización se realice correctamente.

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

Como alternativa, puede usar 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; }
}

También es posible controlar si se requiere una propiedad mediante el modelo de contrato con la propiedad 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; }
}

Parámetros de constructor no opcionales

Antes de .NET 9, la deserialización basada en constructores trataba todos los parámetros de constructor como opcionales, tal como se muestra en el ejemplo siguiente:

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

record Person(string Name, int Age);

A partir de .NET 9, puede crear la flag RespectRequiredConstructorParameters para tratar los parámetros de constructor no opcionales según sea necesario.

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

Conmutador de característica

Puede activar el parámetro de configuración RespectRequiredConstructorParameters de forma global mediante la opción de la característica System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault. Agregue el siguiente elemento de MSBuild al archivo del proyecto (por ejemplo, archivo .csproj):

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

La API RespectRequiredConstructorParametersDefault se ha implementado como una flag voluntaria en .NET 9 para evitar interrumpir las aplicaciones existentes. Si va a escribir una nueva aplicación, le recomendamos que habilite esta flag en el código.

Consulte también