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 anteriormente converteu 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 os valores de null sem os alterar, e o associador trata os valores de 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:

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.

Ação recomendada

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.

APIs afetadas

• APIs Microsoft.Extensions.Configuration