Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
FileConfigurationProvider and its derived types (used by <Microsoft.Extensions.Configuration.JsonConfigurationExtensions.AddJsonFile*>, <Microsoft.Extensions.Configuration.XmlConfigurationExtensions.AddXmlFile*>, and <Microsoft.Extensions.Configuration.IniConfigurationExtensions.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 FileLoadExceptionContext passed to the OnLoadException callback. Only parsing errors were forwarded to that callback. IO errors were unobservable using OnLoadException; instead, they were observable using UnobservedTaskException.
As a consequence, the Exception property on FileLoadExceptionContext passed to OnLoadException was always an InvalidDataException or FileNotFoundException. 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 IOException, but potentially any exception thrown by the configured IFileProvider (including custom providers). Code that unconditionally casts the exception to InvalidDataException or FileNotFoundException can now throw an InvalidCastException or silently mishandle these new exception types.
Type of breaking change
This change is a 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.
Recommended action
- If you detected IO exceptions from
FileConfigurationProvideror a derived type usingTaskScheduler.UnobservedTaskException, move that logic to theOnLoadExceptioncallback. - Verify that any callback registered in
OnLoadExceptioncan handle exceptions of any type, not justInvalidDataExceptionorFileNotFoundException. Avoid unconditional casts, and use pattern matching or type checks instead.
Affected APIs
Collaborate with us on GitHub
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
