[Breaking change]: FileConfigurationSource.OnLoadException callback is called for IO errors

[mrek-msft]

Description

In .NET 11, dotnet/runtime#126093 unified how FileConfigurationProvider and derivate classes handle failures. After fix, IO failures that happens when opening a configuration file (for example, from AddJsonFile, AddXmlFile, AddIniFile or reloads when already loaded file change on disk) are now forwarded to the FileLoadExceptionContext passed to the FileConfigurationSource.OnLoadException callback. Originally only parsing errors were propagated and IO errors was unobservable using this callback. Instead they were observable using TaskScheduler.UnobservedTaskException. After fix, they are no longer observable using TaskScheduler.UnobservedTaskException.

As a consequence of change, previously, the Exception on FileLoadExceptionContext passed to the FileConfigurationSource.OnLoadException callback was always an InvalidDataException or FileNotFoundException. Now the callback may observe additional exception types — most commonly IOException, but potentially any exception thrown by the configured IFileProvider (including custom providers). Code inside an OnLoadException handler that unconditionally casts the exception to InvalidDataException or FileNotFoundException can now throw an InvalidCastException or silently mishandle these new exception types

Version

.NET 11 Preview 7

Previous behavior

• IO errors are not observable using FileConfigurationSource.OnLoadException
• IO errors are observable using TaskScheduler.UnobservedTaskException
• FileConfigurationSource.OnLoadException can observe exception of types InvalidDataException or FileNotFoundException

New behavior

• IO errors are observable using FileConfigurationSource.OnLoadException
• IO errors are not observable using TaskScheduler.UnobservedTaskException, except cases when there is no FileConfigurationSource.OnLoadException callback registered.
• FileConfigurationSource.OnLoadException can observe exception of any type

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

Bug fix for dotnet/runtime#113964

Recommended action

• If detection for IO exception from FileConfigurationProvider or any derived type was done in TaskScheduler.UnobservedTaskException, then it is needed to move such logic to FileConfigurationSource.OnLoadException
• Validate that callbacks registered in FileConfigurationSource.OnLoadException are capable handling of exceptions of any type.

Feature area

Extensions

Affected APIs

• Microsoft.Extensions.Configuration.FileConfigurationSource.OnLoadException
• Microsoft.Extensions.Configuration.Ini.IniConfigurationSource.OnLoadException
• Microsoft.Extensions.Configuration.Json.JsonConfigurationSource.OnLoadException
• Microsoft.Extensions.Configuration.Xml.XmlConfigurationSource.OnLoadException