Partilhar via

Propriedades obrigatórias

  • Artigo

Você pode marcar determinadas propriedades para indicar que elas devem estar presentes na carga JSON para que a desserialização seja bem-sucedida. Da mesma forma, você pode definir uma opção para especificar que todos os parâmetros do construtor não opcionais estão presentes na carga útil JSON. Se uma ou mais dessas propriedades necessárias não estiverem presentes, os métodos lançarão JsonSerializer.Deserialize um JsonExceptionarquivo .

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

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

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

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

O trecho de código a seguir mostra um exemplo de uma propriedade modificada com a palavra-chave required . Essa propriedade deve estar presente na carga 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; }
}

Em alternativa, pode utilizar 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 um imóvel é necessário através do modelo de contrato usando o JsonPropertyInfo.IsRequired imóvel:

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 não opcionais do construtor

Antes do .NET 9, a desserialização baseada em construtor tratava todos os parâmetros do construtor como opcionais, como mostra o 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);

Mudança de funcionalidade

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

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

A RespectRequiredConstructorParametersDefault API 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 que você habilite esse sinalizador em seu código.

Consulte também