Valores nulos preservados na configuração

O fichário de configuração do .NET recupera valores de configuração por meio de provedores de configuração e tenta vincular esses valores às propriedades do objeto. Anteriormente, quando um valor de configuração era nulo, o vinculador tratava-o como se o valor não existisse de todo e, portanto, omitia a ligação. Por outras palavras, não distinguiu entre null valores e valores em falta. Esse comportamento causou confusão significativa para os usuários que esperavam que os valores explicitamente definidos null em sua configuração fossem respeitados e vinculados corretamente.

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

Esta alteração aborda ambas as questões. O fornecedor de configuração JSON agora relata os valores null corretamente sem os alterar, e o encapsulador trata os valores null como entradas válidas, associando-os como qualquer outro valor.

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

Versão introduzida

.NET 10

Comportamento anterior

Anteriormente, quando um valor de configuração era null, o binder tratava-o como se o valor não existisse de todo e, portanto, ignorava o mapeamento. O sistema não distinguia 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 vinculadas a esses valores recebessem uma cadeia de caracteres vazia em vez do esperado null.

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

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

E o código de vinculaçã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)}'")))}");

Output:

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

Explicação do resultado:

• 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?, então o valor original foi mantido.
• Array1: Vinculado a uma matriz contendo duas cadeias de caracteres vazias porque cada null elemento da matriz foi tratado como uma cadeia de caracteres vazia.
• Array2: Foi mantido null porque uma matriz vazia [] no JSON foi ignorada pelo sistema de ligação.

Novo comportamento

A partir do .NET 10, null os valores agora estão devidamente vinculados às suas propriedades correspondentes, incluindo elementos de matriz. Mesmo matrizes vazias são corretamente reconhecidas e vinculadas 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

Trata-se de uma mudança de comportamento.

Motivo da mudança

O comportamento anterior era confuso e frequentemente levava a reclamações dos usuários. Ao resolver esse problema, o processo de vinculaçã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ê pode 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, onde as cadeias de caracteres vazias são vinculadas em vez de null.
• Para outros provedores que oferecem suporte a null valores, remova as null entradas da configuração para replicar o comportamento anterior, onde os valores ausentes são ignorados e os valores de propriedade existentes permanecem inalterados.

APIs afetadas

• Microsoft.Extensions.Configuration Interfaces de Programação de Aplicações (APIs)