Nullwerte, die in der Konfiguration beibehalten werden

Der .NET-Konfigurationsordner ruft Konfigurationswerte über Konfigurationsanbieter ab und versucht, diese Werte an Objekteigenschaften zu binden. Als ein Konfigurationswert zuvor null war, behandelte der Binder ihn so, als ob der Wert überhaupt nicht vorhanden wäre, und übersprang deshalb die Bindung. Mit anderen Worten, es hat nicht zwischen null Werten und fehlenden Werten unterschieden. Dieses Verhalten führte zu erheblichen Verwirrungen für Benutzer, die in ihrer Konfiguration explizit definierte null Werte erwartet haben, dass sie beachtet und ordnungsgemäß gebunden werden.

Darüber hinaus hat der JSON-Konfigurationsanbieter zuvor Werte in der Konfiguration in leere Zeichenfolgen konvertiert null . Dies trug weiter zu Verwirrung bei, da eigenschaften, die an diese Werte gebunden sind, eine leere Zeichenfolge anstelle der erwarteten NULL erhalten würden.

Diese Änderung behebt beide Probleme. Der JSON-Konfigurationsanbieter meldet null Werte jetzt korrekt, ohne sie zu ändern, und der Binder behandelt null-Werte als gültige Eingaben und bindet sie wie jeden anderen Wert.

Das Update enthält auch Verbesserungen zur Unterstützung von Bindungswerten null innerhalb von Arrays und ermöglicht die Bindung leerer Arrays.

Eingeführt in Version

.NET 10

Vorheriges Verhalten

Wenn ein Konfigurationswert null war, behandelte der Binder ihn zuvor so, als ob der Wert überhaupt nicht vorhanden wäre, und ignorierte daher die Bindung. Das System hat zwischen null Werten und fehlenden Werten nicht unterschieden.

Darüber hinaus hat der JSON-Konfigurationsanbieter die Werte in der Konfiguration in leere Zeichenfolgen konvertiert. Dies führte dazu, dass an diese Werte gebundene Eigenschaften eine leere Zeichenfolge anstelle der erwarteten nullempfangen.

Berücksichtigen Sie die folgenden Konfigurationsdateiinhalte appsettings.json :

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

Und der entsprechende Bindungscode:

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

Ausgabe:

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

Erläuterung der Ausgabe:

  • StringProperty: Der null Wert im JSON-Code wurde vom JSON-Anbieter in eine leere Zeichenfolge (""), die den Anfangswert überschreibt, konvertiert.
  • IntProperty: Blieb unverändert (123), da der Anbieter null in eine leere Zeichenfolge konvertierte, die nicht als int? analysiert werden konnte, sodass der ursprüngliche Wert beibehalten wurde.
  • Array1: An ein Array gebunden, das zwei leere Zeichenfolgen enthält, da jedes null Arrayelement als leere Zeichenfolge behandelt wurde.
  • Array2: Ist geblieben null, da ein leeres Array [] im JSON-Code vom Binder ignoriert wurde.

Neues Verhalten

Ab .NET 10 sind null-Werte jetzt ordnungsgemäß an ihre entsprechenden Eigenschaften gebunden, einschließlich Array-Elementen. Selbst leere Arrays werden korrekt erkannt und als leere Arrays gebunden, anstatt ignoriert zu werden.

Wenn Sie dasselbe Codebeispiel ausführen, werden die folgenden Ergebnisse mithilfe des JSON-Konfigurationsanbieters erzeugt:

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

Werttypen, die keine NULL-Werte zulassen

Der Binder bindet null nun auch an Eigenschaften von nicht nullbaren Werttypen (zum Beispiel int, bool oder ein Enum), indem er sie auf den Standardwert des Typs (default(T)) setzt.

Zuvor führte beim JSON-Konfigurationsanbieter das Binden eines null an eine solche Eigenschaft zu einer InvalidOperationException, die in etwa der folgenden entsprach, da der Anbieter null in eine leere Zeichenfolge konvertiert hatte und eine leere Zeichenfolge nicht in den Zielwerttyp konvertiert werden kann:

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

Ab .NET 10 ist die gleiche Bindung erfolgreich, und die Eigenschaft wird auf den Standardwert festgelegt. Beispielsweise führt eine null Bindung an eine DayOfWeek Eigenschaft zu DayOfWeek.Sunday (0), und eine null Bindung an eine int Eigenschaft führt zu 0. Es wird keine Ausnahme ausgelöst.

Anbieter, die einen echten null-Wert speichern, wie z. B. der In-Memory-Anbieter, haben null bereits schon vor .NET 10 an nicht NULL-fähige Werttyp-Eigenschaften gebunden, indem der Standardwert festgelegt wird, und der Konfigurationsquellengenerator entspricht ebenfalls diesem Verhalten. Die Änderung macht den JSON-Anbieter und den spiegelungsbasierten Ordner konsistent mit diesem Verhalten.The change makes the JSON provider and the reflection-based binder consistent with that behavior.

Art der einschneidenden Änderung

Dies ist eine Verhaltensänderung.

Grund für Änderung

Das vorherige Verhalten war verwirrend und führte häufig zu Benutzerbeschwerden. Durch die Behandlung dieses Problems ist der Konfigurationsbindungsprozess jetzt intuitiver und konsistenter, wodurch Verwirrung reduziert und das Verhalten an die Erwartungen der Benutzer angepasst wird.

Wenn Sie das vorherige Verhalten bevorzugen, können Sie Ihre Konfiguration entsprechend anpassen:

  • Ersetzen Sie bei der Verwendung des JSON-Konfigurationsanbieters die null Werte durch leere Zeichenfolgen (""), um das ursprüngliche Verhalten wiederherzustellen, bei dem leere Zeichenfolgen anstelle von null gebunden werden.
  • Entfernen Sie bei anderen Anbietern, die null -Werte unterstützen, die null-Einträge aus der Konfiguration, um das frühere Verhalten zu replizieren, wobei fehlende Werte ignoriert werden und vorhandene Eigenschaftswerte unverändert bleiben.
  • Wenn Sie sich zuvor darauf verlassen haben, dass eine Ausnahme ausgelöst wird, wenn ein Wert vom Typ null an eine Eigenschaft eines Werttyps gebunden wurde, die NULL nicht zulässt, beachten Sie, dass der Binder die Eigenschaft stattdessen nun auf ihren Standardwert setzt. Um einen fehlenden oder auf null gesetzten Wert von einem tatsächlichen Wert zu unterscheiden, legen Sie für die Eigenschaft fest, dass sie NULL-Werte zulässt (z. B. int? oder DayOfWeek?), und prüfen Sie nach der Bindung auf null, oder validieren Sie die Konfiguration explizit.

Betroffene APIs

  • Last updated on