dotnet / dotnet/docs

[Breaking change]: Dependency injection scope disposal aggregates exceptions

Open
#55,654 0 comments 0 reactions 1 assignee Assigned to @gewarren View on GitHub
:watch: Not Triaged breaking-change
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
15h 21m
Merged PRs (30d)
370

Description

### Description

Starting in .NET 11 Preview 2, the built-in dependency injection container continues disposing services after a service's `Dispose()` or `DisposeAsync()` method throws. The change applies when disposing service scopes and root service providers, both synchronously and asynchronously.

After all captured disposable services have been processed, a single disposal exception is rethrown unchanged. If multiple disposal operations fail, an `AggregateException` containing all the exceptions is thrown.

This behaviour was introduced by [dotnet/runtime#123342](https://github.com/dotnet/runtime/pull/123342).

### Version

Other (please put exact version in description textbox)

### Previous behavior

The built-in dependency injection container disposed captured services in reverse order. If a service's `Dispose()` or `DisposeAsync()` method threw an exception, disposal stopped immediately. The exception was propagated unchanged, and services earlier in the disposal sequence were not disposed.

For example, suppose both services in this scope throw from `Dispose()`:

```csharp
_ = scope.ServiceProvider.GetRequiredService();
_ = scope.ServiceProvider.GetRequiredService();

scope.Dispose();
```

`SecondDisposable` was disposed first. When it threw, `FirstDisposable.Dispose()` was not called, and the exception from `SecondDisposable` was propagated.

### New behavior

The built-in dependency injection container attempts to dispose every captured service, even when one or more disposal operations throw. After disposal finishes:

- If exactly one disposal operation failed, its original exception is rethrown.
- If two or more disposal operations failed, an `AggregateException` containing each failure is thrown.

In the preceding example, both `SecondDisposable.Dispose()` and `FirstDisposable.Dispose()` are called. Because both throw, `scope.Dispose()` throws an `AggregateException` containing both exceptions.

The same behaviour applies to asynchronous disposal through `DisposeAsync()`.

### 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.
- [x] **Behavioral change**: Existing binaries might behave differently at run time.

### Reason for change

Although disposal methods are discouraged from throwing exceptions, application and third-party services can still do so. Stopping at the first exception prevented other services from releasing resources such as timers, event handlers, and unmanaged handles. Continuing disposal gives every captured service an opportunity to clean up while still reporting all disposal failures to the caller.

### Recommended action

No action is required if disposal methods do not throw and application code does not depend on disposal stopping after the first failure.

Where possible, update services so that their `Dispose()` and `DisposeAsync()` implementations do not throw. If application code handles exceptions from scope or service-provider disposal, account for both possible exception shapes:

```csharp
try
{
scope.Dispose();
}
catch (AggregateException exception)
{
foreach (Exception innerException in exception.InnerExceptions)
{
// Handle or log each disposal failure.
}
}
catch (Exception exception)
{
// Exactly one disposal operation failed.
}
```

Do not rely on a disposal exception to prevent other services from being disposed. There is no compatibility switch to restore the previous behaviour.

### Feature area

Extensions

### Affected APIs

- `Microsoft.Extensions.DependencyInjection.ServiceProvider.Dispose()`
- `Microsoft.Extensions.DependencyInjection.ServiceProvider.DisposeAsync()`
- `Microsoft.Extensions.DependencyInjection.AsyncServiceScope.Dispose()`
- `Microsoft.Extensions.DependencyInjection.AsyncServiceScope.DisposeAsync()`
- `System.IDisposable.Dispose()` on `Microsoft.Extensions.DependencyInjection.IServiceScope` instances created by the built-in dependency injection container

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.