Condividi tramite

ConfigurationBinder ignora automaticamente gli elementi di matrice non validi

A partire da .NET 8, ConfigurationBinder ignora automaticamente gli elementi della matrice e dell'elenco i cui valori non possono essere convertiti nel tipo di destinazione. In precedenza, gli elementi non riusciti venivano mantenuti come null segnaposto e la raccolta risultante conservava la stessa lunghezza del numero di elementi nell'origine di configurazione.

Versione introdotta

.NET 8

Comportamento precedente

In precedenza, quando si associa una proprietà di matrice o elenco tramite Get<T>(IConfiguration) o Bind(IConfiguration, Object), se il valore di un elemento non può essere convertito nel tipo di destinazione, tale elemento è stato mantenuto come null segnaposto nel risultato. La lunghezza della raccolta corrisponde al numero di elementi nella configurazione.

// Configuration source, for example, appsettings.json:
// "Items": [
//   { "Name": "A", "Interval": 10 },
//   { "Name": "B", "Interval": "a" }   <-- invalid int
// ]

var settings = configuration.GetSection("Items").Get<MyItem[]>();

// .NET 6/7 result:
// settings.Length == 2
// settings[0] = { Name = "A", Interval = 10 }
// settings[1] = null   (conversion failed, placeholder preserved)

Nuovo comportamento

A partire da .NET 8, gli elementi che non riescono nella conversione dei tipi vengono ignorati automaticamente. La raccolta risultante contiene solo elementi associati correttamente e ha una lunghezza inferiore al numero di voci nell'origine di configurazione.

var settings = configuration.GetSection("Items").Get<MyItem[]>();

// .NET 8+ result:
// settings.Length == 1
// settings[0] = { Name = "A", Interval = 10 }

Tipo di cambiamento che interrompe la compatibilità

Questa modifica è una modifica funzionale.

Motivo della modifica

L'implementazione interna di ConfigurationBinder è stata sottoposta a refactoring in .NET 8. Invece di pre-allocare l'array di destinazione e vincolare gli elementi sul posto (lasciava null in caso di errore di conversione), il binder ora raccoglie solo gli elementi correttamente vincolati in un elenco temporaneo prima di creare l'array finale.

Il comportamento precedente è stato problematico anche per tipi di valore come int[]. Per un valore di configurazione non valido, il binder archivierebbe 0, che era indistinguibile da un valore legittimo di 0. Il nuovo comportamento evita questa ambiguità.

  • Abilitare ErrorOnUnknownConfiguration durante lo sviluppo per mostrare immediatamente i valori di configurazione non validi invece di eliminare silenziosamente gli elementi:

    var settings = configuration.GetSection("Items").Get<MyItem[]>(options =>
    options.ErrorOnUnknownConfiguration = true);

    A partire da .NET 8, questa opzione genera ConfigurationBinder anche un'eccezione InvalidOperationException quando un valore non può essere convertito nel tipo di destinazione. Per ulteriori informazioni, vedere ConfigurationBinder throws per valore non corrispondente.

  • Correggere i valori di configurazione non validi. Verificare che tutti i valori nell'origine di configurazione corrispondano ai tipi previsti per il modello associato.

  • Convalidare la lunghezza della raccolta dopo l'associazione se il codice dipende dal numero di elementi corrispondenti all'origine di configurazione.

  • Usare le proprietà di stringa con l'analisi manuale se è necessario gestire adeguatamente i valori non convertibili e mantenere tutti gli elementi dell'array.

Le API interessate

  • Last updated on