ConfigurationBinder 會靜默跳過無效的陣列元素

從 .NET 8 開始，會默默跳過數值無法轉換成目標型別的陣列和清單元素。 過去，失敗的元素會被保留為 null 佔位符，所得集合的長度與組態來源中的元素數量相同。

所推出的版本

.NET 8

以前的行為

過去，當透過Get<T>(IConfiguration)或Bind(IConfiguration, Object)綁定陣列或清單屬性時，如果某個元素的值無法轉換為目標型別，則該元素會在結果中被保留為null佔位符。 集合長度與配置中的元素數量相匹配。

// 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)

新行為

從 .NET 8 開始，失敗型別轉換的元素會被靜默跳過。 所得的集合僅包含成功綁定的元素，且長度比組態來源的條目數短。

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

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

破壞性變更的類型

此變更為行為變更。

變更原因

在 .NET 8 中，ConfigurationBinder 的內部實作已被重構。 綁定器不再預先配置目標陣列並綁定元素（轉換失敗時即保留 null ），而是僅將成功綁定的元素收集成暫存清單，然後再實現最終陣列。

先前的行為對於像 這樣的值型態 int[]也造成問題。 對於無效的設定值，綁定器會儲存 0，這與合法的值 0無法區分。 新的行為避免了這種模糊。

  • 在開發過程中，啟用ErrorOnUnknownConfiguration以立即顯示無效的配置值，而不是無聲地丟棄元素：

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

    從 .NET 8 開始，這個選項也會在ConfigurationBinder無法將值轉換成目標型別時拋出 。InvalidOperationException 更多資訊請參閱 ConfigurationBinder 因不匹配值而引發的例外。

  • 修正無效的設定值。 確保你組態來源中的所有值都符合綁定模型的預期型別。

  • 如果你的程式碼依賴於與設定來源匹配的元素數量，綁定後請驗證集合長度。

  • 如果你需要優雅地處理不可轉換的值並保留所有陣列條目，請使用字串屬性搭配手動解析。

受影響的 API

  • Last updated on