Compartilhar via

Propriedades obrigatórias

  • Artigo

Você pode marcar determinadas propriedades para significar que elas devem estar presentes no conteúdo JSON para que a desserialização tenha êxito. Da mesma forma, você pode definir uma opção para especificar que todos os parâmetros de construtor não opcionais estão presentes na carga JSON. Se uma ou mais dessas propriedades necessárias não estiverem presentes, os métodos JsonSerializer.Deserialize lançarão uma JsonException.

Há três maneiras de marcar uma propriedade ou campo conforme necessário para desserialização JSON:

Para especificar que todos os parâmetros de construtor não opcionais são necessários para a desserialização JSON, defina a opção JsonSerializerOptions.RespectRequiredConstructorParameters (ou, para geração de origem, a propriedade RespectRequiredConstructorParameters) como true. Para obter mais informações, consulte a seção Parâmetros de construtor não opcionais.

Da perspectiva do serializador, o modificador C# required e o atributo [JsonRequired] são equivalentes e ambos são mapeados para a mesma parte dos metadados, que é JsonPropertyInfo.IsRequired. Na maioria dos casos, você simplesmente usaria a palavra-chave integrada de C#. No entanto, você deve usar JsonRequiredAttribute nos seguintes casos:

  • Se estiver usando uma linguagem de programação diferente de C# ou uma versão de nível inferior de C#.
  • Se quiser apenas aplicar o requisito à desserialização JSON.
  • Se estiver usando a serialização System.Text.Json no modo de geração de origem. Nesse caso, seu código não será compilado se você usar o modificador required, pois a geração de origem ocorrerá em tempo de compilação.

O snippet de código a seguir mostra um exemplo de uma propriedade modificada com a palavra-chave required. Essa propriedade deve estar presente no conteúdo JSON para que a desserialização seja bem-sucedida.

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, você pode 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; }
}

Também é possível controlar se uma propriedade é necessária por meio do modelo de contrato usando a propriedade 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 construtor não opcionais

Antes do .NET 9, a desserialização baseada em construtor tratava todos os parâmetros do construtor como opcionais, como no exemplo a seguir:

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

record Person(string Name, int Age);

A partir do .NET 9, você pode definir o sinalizador RespectRequiredConstructorParameters para tratar parâmetros de construtor não opcionais conforme necessário.

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

Opção de recurso

Você pode ativar a configuração RespectRequiredConstructorParameters globalmente com a opção de recurso System.Text.Json.Serialization.RespectRequiredConstructorParametersDefault. Adicione o seguinte item do MSBuild ao arquivo de projeto (por exemplo, arquivo .csproj):

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

A API RespectRequiredConstructorParametersDefault foi implementada como um sinalizador de aceitação no .NET 9 para evitar a interrupção de aplicativos existentes. Se você estiver escrevendo um novo aplicativo, é altamente recomendável habilitar esse sinalizador no seu código.

Confira também