From 277a9c26d9864afcaf63708fdc0bae79c02d821e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Aug 2026 17:12:20 +0000 Subject: [PATCH 1/3] Initial plan From 361cf024a1d76927cf7d7ee69971738d5ceaca24 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 5 Aug 2026 17:15:11 +0000 Subject: [PATCH 2/3] Add breaking change doc for FileConfigurationSource.OnLoadException IO errors Co-authored-by: gewarren <24882762+gewarren@users.noreply.github.com> --- docs/core/compatibility/11.md | 1 + ...urationsource-onloadexception-io-errors.md | 63 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 66 insertions(+) create mode 100644 docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 51b5589505918..e950a60229b2e 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -60,6 +60,7 @@ See [Breaking changes in EF Core 11](/ef/core/what-is-new/ef-core-11.0/breaking- | Title | Type of change | |-------|-------------------| | [ChangeToken.OnChange async overloads rebind existing Task-returning callbacks](extensions/11/changetoken-onchange-async-overloads-rebind-callbacks.md) | Behavioral change | +| [FileConfigurationSource.OnLoadException callback is called for IO errors](extensions/11/fileconfigurationsource-onloadexception-io-errors.md) | Behavioral change | | [IHost.RunAsync and IHost.StopAsync throw when a BackgroundService fails](extensions/11/ihost-runasync-stopasync-throw-backgroundservice-failure.md) | Behavioral change | | [Some Microsoft.Extensions packages included in shared framework](extensions/11/extensions-in-shared-framework.md) | Behavioral change | diff --git a/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md b/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md new file mode 100644 index 0000000000000..b5f994e532931 --- /dev/null +++ b/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md @@ -0,0 +1,63 @@ +--- +title: "Breaking change: FileConfigurationSource.OnLoadException callback is called for IO errors" +description: "Learn about the breaking change in .NET 11 where FileConfigurationSource.OnLoadException is called for IO errors in addition to parsing errors." +ms.date: 08/05/2026 +ai-usage: ai-assisted +--- + +# FileConfigurationSource.OnLoadException callback is called for IO errors + + and its derived types (used by `AddJsonFile`, `AddXmlFile`, and `AddIniFile`) now forward IO errors to the `OnLoadException` callback in addition to parsing errors. + +## Version introduced + +.NET 11 Preview 7 + +## Previous behavior + +Previously, IO errors that occurred when a configuration file was opened (for example, from `AddJsonFile`, `AddXmlFile`, `AddIniFile`, or a reload triggered when an already-loaded file changed on disk) weren't forwarded to the passed to the callback. Only parsing errors were forwarded to that callback. IO errors were unobservable using `OnLoadException`; instead, they were observable using . + +As a consequence, the `Exception` property on `FileLoadExceptionContext` passed to `OnLoadException` was always an or . Code that unconditionally cast the exception to one of those types worked correctly. + +## New behavior + +Starting in .NET 11, IO errors are forwarded to the `FileLoadExceptionContext` passed to the `OnLoadException` callback. IO errors are no longer observable using `TaskScheduler.UnobservedTaskException`, except when no `OnLoadException` callback is registered. + +As a consequence, the `Exception` property on `FileLoadExceptionContext` can now be an exception of any type—most commonly , but potentially any exception thrown by the configured (including custom providers). Code that unconditionally casts the exception to `InvalidDataException` or `FileNotFoundException` can now throw an or silently mishandle these new exception types. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change is a bug fix. Configuration file IO errors are meaningful load failures, and code that registers an `OnLoadException` callback expects to observe all failures that occur while a configuration file is loaded, not just parsing errors. For more information, see [dotnet/runtime#113964](https://github.com/dotnet/runtime/issues/113964). + +## Recommended action + +- If you detected IO exceptions from `FileConfigurationProvider` or a derived type using `TaskScheduler.UnobservedTaskException`, move that logic to the `OnLoadException` callback. +- Verify that any callback registered in `OnLoadException` can handle exceptions of any type, not just `InvalidDataException` or `FileNotFoundException`. Avoid unconditional casts, and use pattern matching or type checks instead. + +```csharp +options.OnLoadException = context => +{ + // Handle any exception type, not just InvalidDataException or FileNotFoundException. + if (context.Exception is IOException ioException) + { + // Handle IO errors. + } + else if (context.Exception is InvalidDataException invalidDataException) + { + // Handle parsing errors. + } + + context.Ignore = true; +}; +``` + +## Affected APIs + +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 0582ff971eadc..4ac256b7027e7 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -50,6 +50,8 @@ items: items: - name: ChangeToken.OnChange async overloads rebind existing Task-returning callbacks href: extensions/11/changetoken-onchange-async-overloads-rebind-callbacks.md + - name: FileConfigurationSource.OnLoadException callback is called for IO errors + href: extensions/11/fileconfigurationsource-onloadexception-io-errors.md - name: IHost.RunAsync and IHost.StopAsync throw when a BackgroundService fails href: extensions/11/ihost-runasync-stopasync-throw-backgroundservice-failure.md - name: Some Microsoft.Extensions packages included in shared framework From 43ad98b474f2ed907f8d4b84bab38b6ba688dae0 Mon Sep 17 00:00:00 2001 From: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Date: Wed, 5 Aug 2026 14:06:07 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- ...urationsource-onloadexception-io-errors.md | 24 ++----------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md b/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md index b5f994e532931..5417cf878c590 100644 --- a/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md +++ b/docs/core/compatibility/extensions/11/fileconfigurationsource-onloadexception-io-errors.md @@ -7,7 +7,7 @@ ai-usage: ai-assisted # FileConfigurationSource.OnLoadException callback is called for IO errors - and its derived types (used by `AddJsonFile`, `AddXmlFile`, and `AddIniFile`) now forward IO errors to the `OnLoadException` callback in addition to parsing errors. + and its derived types (used by , , and ) now forward IO errors to the callback in addition to parsing errors. ## Version introduced @@ -38,26 +38,6 @@ This change is a bug fix. Configuration file IO errors are meaningful load failu - If you detected IO exceptions from `FileConfigurationProvider` or a derived type using `TaskScheduler.UnobservedTaskException`, move that logic to the `OnLoadException` callback. - Verify that any callback registered in `OnLoadException` can handle exceptions of any type, not just `InvalidDataException` or `FileNotFoundException`. Avoid unconditional casts, and use pattern matching or type checks instead. -```csharp -options.OnLoadException = context => -{ - // Handle any exception type, not just InvalidDataException or FileNotFoundException. - if (context.Exception is IOException ioException) - { - // Handle IO errors. - } - else if (context.Exception is InvalidDataException invalidDataException) - { - // Handle parsing errors. - } - - context.Ignore = true; -}; -``` - ## Affected APIs -- -- -- -- +-