Hodnoty null zachované v konfiguraci

Pořadač konfigurace .NET načte hodnoty konfigurace prostřednictvím zprostředkovatelů konfigurace a pokusí se tyto hodnoty svázat s vlastnostmi objektu. Dříve, když byla hodnota konfigurace null, binder ji považoval za neexistující a proto přeskočil vazbu. Jinými slovy, nerozlišovala mezi null hodnotami a chybějícími hodnotami. Toto chování způsobilo značné nejasnosti pro uživatele, kteří ve své konfiguraci očekávali explicitně definované null hodnoty, aby se respektovaly a správně vázaly.

Navíc poskytovatel konfigurace JSON dříve převáděl null hodnoty v konfiguraci na prázdné řetězce. To dále přispělo k nejasnostem, protože vlastnosti vázané na tyto hodnoty by místo očekávané hodnoty null obdržely prázdný řetězec.

Tato změna řeší oba problémy. Zprostředkovatel konfigurace JSON teď správně hlásí null hodnoty, aniž by je měnil, a binder považuje hodnoty za platné vstupy null a váže je jako jakoukoli jinou hodnotu.

Aktualizace také zahrnuje vylepšení podpory hodnot vazeb null v rámci polí a umožňuje vazbu prázdných polí.

Verze byla představena

.NET 10

Předchozí chování

Dříve, když byla hodnota konfigurace null, binder ji považoval za neexistující a proto přeskočil vazbu. Systém nerozlišoval mezi null hodnotami a chybějícími hodnotami.

Kromě toho zprostředkovatel konfigurace JSON převedl null hodnoty v konfiguraci na prázdné řetězce. To způsobilo, že vlastnosti vázané na tyto hodnoty obdržely prázdný řetězec místo očekávaného null.

Zvažte následující obsah konfiguračního souboru appsettings.json :

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

A odpovídající kód vazby:

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)}'")))}");

Výstup:

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

Vysvětlení výstupu:

• StringProperty: Hodnota null ve formátu JSON byla zprostředkovatelem JSON převedena na prázdný řetězec (""), což přepsalo počáteční hodnotu.
• IntProperty: Zůstal beze změny (123), protože zprostředkovatel převeděl null na prázdný řetězec, který se nepodařilo analyzovat jako int?, takže původní hodnota byla zachována.
• Array1: Vázáno na pole obsahující dva prázdné řetězce, protože každý null prvek pole byl považován za prázdný řetězec.
• Array2: Zůstalo null protože prázdné pole [] ve formátu JSON bylo pořadačem ignorováno.

Nové chování

Počínaje rozhraním .NET 10 null jsou nyní hodnoty správně svázané s odpovídajícími vlastnostmi, včetně prvků pole. Dokonce i prázdná pole jsou správně rozpoznána a svázána jako prázdná pole, spíše než být ignorována.

Spuštění stejné ukázky kódu vytvoří následující výsledky pomocí zprostředkovatele konfigurace JSON:

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

Typ zásadní změny

Jedná se o změnu chování.

Důvod změny

Předchozí chování bylo matoucí a často vedlo k stížnostem uživatelů. Řešením tohoto problému se proces vazby konfigurace stává intuitivnějším a konzistentnějším, což snižuje nejasnosti a slaďuje chování s očekáváními uživatelů.

Doporučená akce

Pokud dáváte přednost předchozímu chování, můžete konfiguraci odpovídajícím způsobem upravit:

• Při použití zprostředkovatele konfigurace JSON nahraďte null hodnoty prázdnými řetězci ("") k obnovení původního chování, kde jsou prázdné řetězce vázány místo null.
• U jiných zprostředkovatelů, kteří podporují null hodnoty, odeberte null položky z konfigurace, aby se replikovaly dřívější chování, kde se chybějící hodnoty ignorují a existující hodnoty vlastností zůstanou beze změny.

Ovlivněná rozhraní API

• Microsoft.Extensions.Configuration Rozhraní API