# IDisposable vs IAsyncDisposable in ASP.NET Core: Resource Cleanup — Enterprise Decision Guide Resource cleanup is one of the most quietly consequential decisions in a production .NET application. The difference between a service that correctly implements `IDisposable` versus one that should implement `IAsyncDisposable` — or both — can be the difference between a healthy long-running API and one that leaks connections, deadlocks under load, or throws cryptic `ObjectDisposedException` errors at 3 AM. Understanding `IDisposable` vs `IAsyncDisposable` in ASP.NET Core is not just a correctness question; it is an architectural decision with real consequences at scale. --- > 🎁 **Want implementation-ready .NET source code you can drop straight into your project?** Join Coding Droplets on Patreon for exclusive tutorials, premium code samples, and early access to new content. 👉 **https://www.patreon.com/CodingDroplets** --- ## What Is IDisposable and Why Does It Still Matter? `IDisposable` has been a core part of .NET since version 1.0. It defines a single `Dispose()` method that gives your type a deterministic, synchronous path to release resources — closing file handles, returning pooled connections, cancelling background work. ASP.NET Core's dependency injection container automatically calls `Dispose()` on scoped and singleton services that implement `IDisposable` when those services go out of scope or when the host shuts down. This automatic lifecycle management is one of the container's most useful — and most misunderstood — behaviours. The pattern remains essential for any type that wraps unmanaged resources, database connections, file streams, or anything that must be explicitly released. The majority of .NET BCL types that need cleanup still implement `IDisposable`. ## What Is IAsyncDisposable and When Was It Introduced? `IAsyncDisposable` was added in .NET Core 3.0 as a response to a real problem: synchronous `Dispose()` cannot `await` anything. If your cleanup logic involves flushing an async stream, gracefully closing a WebSocket, draining a `Channel`, or waiting for an in-flight operation to complete, a synchronous `Dispose()` forces you to either block the thread or silently skip the async cleanup. The interface adds a single `DisposeAsync()` method that returns a `ValueTask`. It works with `await using` statements, and ASP.NET Core's DI container has supported `IAsyncDisposable` since .NET Core 3.1 — meaning the container will call `DisposeAsync()` (and `await` it) during host shutdown and scope teardown, provided the host is being shut down asynchronously. ## The Core Question: Which Interface Should Your Type Implement? This is the decision point that most articles gloss over. The answer depends on three questions: **1. Does your cleanup work involve any I/O, network, or async operations?** If yes: implement `IAsyncDisposable`. Examples include closing a database connection pool, flushing a log buffer to a remote sink, gracefully stopping an `HttpClient`-dependent service, or waiting for a background worker to drain its queue. **2. Can your type be consumed by non-async callers or in synchronous contexts?** If your type may be consumed in `using` blocks in synchronous code, or in frameworks that only call `Dispose()`, implement both interfaces. The canonical approach is to implement `IAsyncDisposable` as the primary path and have `Dispose()` call a synchronous fallback (or block on `DisposeAsync().AsTask().GetAwaiter().GetResult()` only as a last resort — not recommended in high-throughput services). **3. Does your cleanup only release managed resources through other `IDisposable` members?** If all your cleanup involves calling `Dispose()` on other `IDisposable` members with no async work, `IDisposable` alone is correct and simpler. ## Decision Matrix: IDisposable vs IAsyncDisposable | Scenario | Recommended Interface | Reasoning | |---|---|---| | File streams, database readers | `IDisposable` | Synchronous close is safe; blocking is fine | | HttpClient, gRPC channel cleanup | `IAsyncDisposable` | Connection teardown benefits from async drain | | Channels / producer-consumer queues | `IAsyncDisposable` | DisposeAsync can await queue drain before closing | | Background service that wraps a scoped worker | `IAsyncDisposable` | Async stop is needed to avoid torn state | | Type consumed in sync test harnesses | Both | Ensure compatibility with both contexts | | Simple wrapper over BCL `IDisposable` types | `IDisposable` | No async work required; keep it simple | | Custom DbContext with SaveChanges-on-dispose | `IAsyncDisposable` | Use `DisposeAsync` to call `SaveChangesAsync` | ## How Does ASP.NET Core's DI Container Handle Disposal? Understanding the container's disposal behaviour is critical for avoiding bugs in production. **Scoped services** are disposed at the end of each HTTP request (when the request scope is disposed). If a scoped service implements `IAsyncDisposable`, the container calls `DisposeAsync()` asynchronously at scope teardown — assuming the middleware pipeline properly awaits the disposal of the scope. **Singleton services** are disposed when the host shuts down via `IHost.StopAsync()`. If the host shuts down asynchronously (the standard path in .NET 6+), `DisposeAsync()` is called on singletons that implement it. **Transient services** are owned by the container and disposed when the containing scope is disposed — but this is where a major trap lives. ## The Transient IDisposable Trap Registering a transient service that implements `IDisposable` is one of the most common resource leak patterns in ASP.NET Core. The container tracks every transient `IDisposable` it creates in the current scope so it can dispose of them at scope teardown. In a web application, this means every transient `IDisposable` created during a request is held in memory until the request ends. For heavy services — database connections, large file handles — this extends the object's lifetime far beyond what callers intend. For high-throughput APIs, this causes allocation pressure and delayed resource return. **The rule from Microsoft's official guidance:** Do not register `IDisposable` instances with a transient lifetime unless you fully understand and accept the extended scope lifetime. Use the factory pattern instead if you need short-lived disposables that the caller owns and disposes directly. ## Is Your Type the Owner of Its Resources? Ownership is the most underrated concept in .NET resource management. `IDisposable` and `IAsyncDisposable` only make sense on the *owner* of a resource — the type that created the resource and is responsible for freeing it. If your service receives an `HttpClient` via constructor injection, you are not the owner; you should not dispose it. If your service creates a `DbConnection` directly (rare with EF Core but possible in Dapper scenarios), you are the owner and must dispose it. Violations of ownership semantics are a common source of `ObjectDisposedException` in production, especially when services are incorrectly disposed by the container after the caller has already released them. ## Implementing Both Interfaces: The Right Pattern When you genuinely need both (for compatibility), the correct pattern follows Microsoft's documentation precisely. The `DisposeAsync()` method handles the full async cleanup. The `Dispose()` method handles synchronous-only cleanup, disposes managed resources synchronously, and suppresses finalization. The two paths should not duplicate work — use a private `_disposed` flag to guard both. The key anti-pattern to avoid: calling `DisposeAsync().AsTask().GetAwaiter().GetResult()` inside `Dispose()`. This blocks the thread and can deadlock in ASP.NET Core's synchronisation context if the async disposal path captures it. The recommended approach when you must support both is to split cleanup into two paths: one for synchronous resources (file handles, managed `IDisposable` members) handled in `Dispose()`, and one for async resources (connections, channels) handled only in `DisposeAsync()`. Accept that sync callers will miss the async cleanup, and document this explicitly. ## What Does This Mean for Your ASP.NET Core API Team? In practice, most enterprise ASP.NET Core services should prefer `IAsyncDisposable` when any cleanup involves I/O. The host's shutdown sequence is asynchronous, scoped lifetime teardown is asynchronous, and `await using` is idiomatic in modern C#. Defaulting to `IDisposable` for convenience is increasingly the wrong default. Where `IDisposable` remains appropriate: simple services that hold managed resources, wrapper types over BCL `IDisposable` members, and types consumed in mixed sync/async contexts where both paths must be supported. This connects directly to how you structure long-running services. If you need to see how disposable services fit into a full production API — alongside background workers, scoped database work, and graceful shutdown — Chapter 12 of the [ASP.NET Core Web API: Zero to Production course](https://aspnetcoreapi.codingdroplets.com/) covers exactly this: background jobs, service lifetimes, and the shutdown coordination patterns that prevent data loss. ## Anti-Patterns to Avoid **Disposing services you don't own.** If the DI container created it and owns it, let the container dispose it. Don't call `Dispose()` manually on injected dependencies. **Ignoring `IAsyncDisposable` in singletons.** Singletons that hold async resources (channels, persistent connections) but only implement `IDisposable` will skip async cleanup during shutdown. This causes data loss in scenarios like draining a message queue. **Using `GC.SuppressFinalize` incorrectly.** Call it in `Dispose()` to prevent the finalizer from running when the object has already been deterministically disposed. Forgetting this does not cause bugs immediately but wastes GC resources at scale. **Not guarding against multiple disposal.** Always use a private `_disposed` flag and check it at the start of both `Dispose()` and `DisposeAsync()`. Double-disposal is easy to trigger in test scenarios and edge cases. **Using `async void` in disposal paths.** Never use `async void` in any disposal method. Use `ValueTask` (via `DisposeAsync`) for async paths, and synchronous void for `Dispose()`. `async void` exceptions are unobservable and will crash your process. --- ☕ Prefer a one-time tip? [Buy us a coffee](https://buymeacoffee.com/codingdroplets) — every bit helps keep the content coming! --- ## FAQ ### When should I implement IAsyncDisposable instead of IDisposable in an ASP.NET Core service? Implement `IAsyncDisposable` when your cleanup logic involves any asynchronous work: flushing async streams, closing network connections gracefully, draining queues, or awaiting background work completion. The ASP.NET Core DI container fully supports async disposal since .NET Core 3.1, so there is no reason to block on async cleanup in services registered with the container. ### Does ASP.NET Core's DI container automatically call DisposeAsync? Yes, when services are registered with scoped or singleton lifetimes and implement `IAsyncDisposable`, the container calls `DisposeAsync()` and awaits it during scope teardown (end of HTTP request for scoped services) and host shutdown (for singletons). This requires the host to shut down via the standard asynchronous shutdown path, which is the default in .NET 6 and later. ### Can I register both IDisposable and IAsyncDisposable on the same service? Yes. The DI container checks for `IAsyncDisposable` first when disposing. If the service implements `IAsyncDisposable`, `DisposeAsync()` is called. If it only implements `IDisposable`, `Dispose()` is called. If you implement both, the container will use `DisposeAsync()` and not call `Dispose()` — so your `Dispose()` implementation should not duplicate async cleanup that `DisposeAsync()` handles. ### Why is registering a transient IDisposable service dangerous in ASP.NET Core? The DI container tracks all transient `IDisposable` instances it creates within a scope, so it can dispose them when the scope ends. In a web app, this means every transient `IDisposable` created during a request is kept alive until the request ends — extending its lifetime beyond what callers expect. For resource-heavy types, this increases memory pressure and delays resource return. Use factories or have the caller own and dispose the instance directly instead. ### What is the correct pattern when I need to support both IDisposable and IAsyncDisposable? Separate the cleanup work: let `DisposeAsync()` handle all async resource release, and let `Dispose()` only handle synchronous resources. Accept that callers using `Dispose()` will miss the async cleanup (document this). Never block on `DisposeAsync()` inside `Dispose()` in ASP.NET Core services — the risk of deadlock on the captured synchronisation context is real. Always guard both methods with a `_disposed` flag to handle multiple-disposal safely. ### How does IAsyncDisposable interact with the using statement in C#? Use `await using` to call `DisposeAsync()` at the end of a scope. The `await using` statement was introduced in C# 8.0 alongside `IAsyncDisposable`. It calls `DisposeAsync()` and awaits the returned `ValueTask`. If you use a plain `using` statement with an `IAsyncDisposable`-only type, you will get a compile warning because `Dispose()` will not be found. Always match `await using` with `IAsyncDisposable`. ### Are there real-world examples where missing IAsyncDisposable causes production bugs? Yes. The most common examples are: singleton services holding open `Channel` queues that skip graceful drain on shutdown, causing message loss; services wrapping `HttpMessageHandler` or persistent WebSocket connections that close abruptly instead of handshaking; and Dapper-based services that hold open `IDbConnection` instances and miss connection return on async teardown. These bugs are silent in development and surface under production load or during rolling deployments.