Valores nulos preservados na configuração

O vinculador de configuração do .NET recupera valores de configuração por meio de provedores de configuração e tenta vinculá-los às propriedades do objeto. Anteriormente, quando um valor de configuração era nulo, o vinculador o tratava como se o valor não existisse e, portanto, ignorava a vinculação. Em outras palavras, ele não distinguia entre null valores e valores ausentes. Esse comportamento causou confusão significativa para os usuários que esperavam que valores definidos null explicitamente em sua configuração fossem respeitados e associados corretamente.

Além disso, o provedor de configuração JSON converteu anteriormente null valores na configuração em cadeias de caracteres vazias. Isso contribuiu ainda mais para a confusão, pois as propriedades associadas a esses valores receberiam uma cadeia de caracteres vazia em vez do nulo esperado.

Essa alteração resolve os dois problemas. O provedor de configuração JSON agora relata corretamente valores null sem os alterar, e o associador trata os valores null como entradas válidas, associando-os como qualquer outro valor.

A atualização também inclui melhorias para dar suporte a valores de associação null dentro de matrizes e permite a associação de matrizes vazias.

Versão introduzida

.NET 10

Comportamento anterior

Anteriormente, quando um valor de configuração era null, o vinculador o tratava como se o valor não existisse e, assim, pulava a associação. O sistema não distinguiu entre null valores e valores ausentes.

Além disso, o provedor de configuração JSON converteu null valores na configuração em cadeias de caracteres vazias. Isso fez com que as propriedades associadas a esses valores recebessem uma cadeia de caracteres vazia em vez do esperado null.

Considere o seguinte conteúdo do arquivo appsettings.json de configuração:

{
    "NullConfiguration": {
        "StringProperty": null,
        "IntProperty": null,
        "Array1": [null, null],
        "Array2": []
    }
}

E o código de associação correspondente:

public class NullConfiguration
{
    public NullConfiguration()
    {
        // Initialize with non-default value to
        // ensure binding overrides these values.
        StringProperty = "Initial Value";
        IntProperty = 123;
    }
    public string? StringProperty { get; set; }
    public int? IntProperty { get; set; }
    public string[]? Array1 { get; set; }
    public string[]? Array2 { get; set; }
}

var configuration = new ConfigurationBuilder()
                    .AddJsonFile("appsettings.json")
                    .Build().GetSection("NullConfiguration");

// Now bind the configuration.
NullConfiguration? result = configuration.Get<NullConfiguration>();

Console.WriteLine($"StringProperty: '{result!.StringProperty}', intProperty: {(result!.IntProperty.HasValue ? result!.IntProperty : "null")}");
Console.WriteLine($"Array1: {(result!.Array1 is null ?
    "null" : string.Join(", ", result!.Array1.Select(a => $"'{(a is null ? "null" : a)}'")))}");
Console.WriteLine($"Array2: {(result!.Array2 is null ?
    "null" : string.Join(", ", result!.Array2.Select(a => $"'{(a is null ? "null" : a)}'")))}");

Saída:

StringProperty: '', intProperty: 123
Array1: '', ''
Array2: null

Explicação da saída:

  • StringProperty: o null valor no JSON foi convertido pelo provedor JSON em uma cadeia de caracteres vazia (""), substituindo o valor inicial.
  • IntProperty: permaneceu inalterado (123) porque o provedor converteu null em uma cadeia de caracteres vazia, que não pôde ser analisada como um int?, portanto, o valor original foi retido.
  • Array1: associado a uma matriz que contém duas cadeias de caracteres vazias porque cada null elemento de matriz foi tratado como uma cadeia de caracteres vazia.
  • Array2: permaneceu null desde que uma matriz [] vazia no JSON foi ignorada pelo associador.

Novo comportamento

A partir do .NET 10, null os valores agora estão devidamente associados às suas propriedades correspondentes, incluindo elementos de matriz. Mesmo matrizes vazias são reconhecidas corretamente e associadas como matrizes vazias em vez de serem ignoradas.

A execução do mesmo exemplo de código produz os seguintes resultados usando o provedor de configuração JSON:

StringProperty: 'null', intProperty: null
Array1: 'null', 'null'
Array2:

Tipos de valor não anuláveis

O vinculador agora também vincula null a propriedades não anuláveis do tipo valor (por exemplo, int, bool ou uma enumeração), atribuindo-lhes o valor padrão do tipo (default(T)).

Anteriormente, com o provedor de configuração JSON, vincular um null a tal propriedade gerava uma InvalidOperationException semelhante à seguinte, porque o provedor havia convertido o null em uma cadeia de caracteres vazia, e uma cadeia de caracteres vazia não pode ser convertida para o tipo de valor de destino:

Failed to convert configuration value at 'SomeSection:DayOfWeekProperty' to type 'System.DayOfWeek'.

A partir do .NET 10, a mesma associação é bem-sucedida e a propriedade é definida como seu valor padrão. Por exemplo, um null associado a uma DayOfWeek propriedade resulta em DayOfWeek.Sunday (0) e um null associado a uma int propriedade resulta em 0. Nenhuma exceção é gerada.

Provedores que armazenam um valor real null, como o provedor em memória, já vinculavam null a propriedades não anuláveis do tipo valor ao definir o valor padrão, mesmo antes do .NET 10, e o gerador de origem de configuração também segue esse mesmo comportamento. A alteração deixa o provedor JSON e o associador baseado em reflexão consistentes com esse comportamento.

Tipo de mudança disruptiva

Essa é uma mudança comportamental.

Motivo da alteração

O comportamento anterior era confuso e frequentemente levava a reclamações de usuários. Ao resolver esse problema, o processo de associação de configuração agora é mais intuitivo e consistente, reduzindo a confusão e alinhando o comportamento com as expectativas do usuário.

Se preferir o comportamento anterior, você poderá ajustar sua configuração de acordo:

  • Ao usar o provedor de configuração JSON, substitua null valores por cadeias de caracteres vazias ("") para restaurar o comportamento original, em que cadeias de caracteres vazias são associadas em vez de null.
  • Para outros provedores que dão suporte a valores null, remova as entradas null da configuração para replicar o comportamento anterior, em que os valores ausentes são ignorados e os valores de propriedade existentes permanecem inalterados.
  • Se você anteriormente dependia de uma exceção quando um valor null estava vinculado a uma propriedade de tipo valor não anulável, o vinculador agora define a propriedade como o valor padrão. Para distinguir um valor ausente ou null de um valor real, torne a propriedade anulável (por exemplo, int? ou DayOfWeek?) e verifique se há null após a associação ou valide a configuração explicitamente.

APIs afetadas

  • Last updated on