When should a type implement IAsyncDisposable, how does await using work, and how do you implement both IDisposable and IAsyncDisposable correctly?

1. ValueTask and why disposal uses it

Most DisposeAsync calls either have nothing to do (already disposed, empty buffer) or complete synchronously. ValueTask avoids allocating a Task for those cases. Rules for consuming a ValueTask:

• Await it once.
• Don't .Result it before completion.
• Don't store it and await later from multiple places.

CA2012 flags misuse.

2. ConfigureAwait with await using

TaskAsyncEnumerableExtensions.ConfigureAwait(this IAsyncDisposable, bool) returns a ConfiguredAsyncDisposable, which await using accepts. Because the wrapper isn't the resource, declare the resource separately:

var stream = new FileStream(path, FileMode.Create, FileAccess.Write, FileShare.None, 4096, useAsync: true);
await using (stream.ConfigureAwait(false))
{
    await stream.WriteAsync(data).ConfigureAwait(false);
}

Writing await using (var s = stream.ConfigureAwait(false)) compiles, but s is the wrapper, not the FileStream. In ASP.NET Core app code there's no synchronisation context, so this is mostly relevant for libraries.

3. A derived class with async cleanup

public class BufferedSink : IDisposable, IAsyncDisposable
{
    private readonly Stream _stream;
    private bool _disposed;

    public BufferedSink(Stream stream) => _stream = stream;

    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);
        Dispose(disposing: false);
        GC.SuppressFinalize(this);
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if (_disposed) return;
        _disposed = true;
        await _stream.FlushAsync().ConfigureAwait(false);
        await _stream.DisposeAsync().ConfigureAwait(false);
    }

    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (_disposed) return;
        _disposed = true;
        if (disposing) _stream.Dispose();
    }
}

public sealed class CompressingSink : BufferedSink
{
    private readonly GZipStream _zip;
    public CompressingSink(Stream s) : base(s) => _zip = new GZipStream(s, CompressionLevel.Fastest, leaveOpen: true);

    protected override async ValueTask DisposeAsyncCore()
    {
        try { await _zip.DisposeAsync().ConfigureAwait(false); }   // write gzip footer first
        finally { await base.DisposeAsyncCore().ConfigureAwait(false); }
    }

    protected override void Dispose(bool disposing)
    {
        try { if (disposing) _zip.Dispose(); }
        finally { base.Dispose(disposing); }
    }
}

4. How the DI container chooses

ServiceProviderEngineScope tracks disposables in creation order and, on disposal:

5. Types in the BCL with async disposal

6. Shutdown deadlines

Async disposal at shutdown runs within the host's shutdown timeout (HostOptions.ShutdownTimeout, 30 seconds by default in recent versions). Flushes that call remote services should respect a cancellation token or timeout so a slow dependency can't stall shutdown indefinitely.

7. Version notes

8. Try it yourself

1. Run the code example: the log is flushed by DisposeAsync, and the synchronous scope dispose throws for the async-only service.
2. Change AsyncOnlyExporter to implement both interfaces, dispose a sync scope, and confirm only Dispose() runs.
3. Write a Dispose() that does Task.Delay(2000).GetAwaiter().GetResult() and dispose 200 of them in parallel; watch thread pool starvation with dotnet-counters.
4. Implement the CompressingSink hierarchy above and confirm the gzip file is valid after await using.
5. Add a Timer whose callback takes 1 second, then compare timer.Dispose() vs await timer.DisposeAsync() timing.
6. Enable CA2012 and CA2215 and introduce a mistake each catches.

using System.Text;
using Microsoft.Extensions.DependencyInjection;

await using (var log = new AsyncLogWriter("app.log"))
{
    await log.WriteAsync("started");
    await log.WriteAsync("finished");
} // DisposeAsync flushes the buffer asynchronously
Console.WriteLine(File.ReadAllText("app.log"));

var services = new ServiceCollection().AddScoped<AsyncOnlyExporter>().BuildServiceProvider();

// Correct: async scope
await using (AsyncServiceScope scope = services.CreateAsyncScope())
    scope.ServiceProvider.GetRequiredService<AsyncOnlyExporter>();

// Wrong: synchronous dispose of a scope holding an IAsyncDisposable-only service
try
{
    using IServiceScope syncScope = services.CreateScope();
    syncScope.ServiceProvider.GetRequiredService<AsyncOnlyExporter>();
}
catch (InvalidOperationException ex)
{
    Console.WriteLine($"Sync dispose failed: {ex.Message}");
}

public class AsyncLogWriter : IDisposable, IAsyncDisposable
{
    private readonly FileStream _file;
    private readonly StringBuilder _buffer = new();
    private bool _disposed;

    public AsyncLogWriter(string path) => _file = new FileStream(path, FileMode.Create, FileAccess.Write, FileShare.Read, 4096, useAsync: true);

    public Task WriteAsync(string line)
    {
        ObjectDisposedException.ThrowIf(_disposed, this);
        _buffer.AppendLine(line);
        return Task.CompletedTask;
    }

    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);
        Dispose(disposing: false);
        GC.SuppressFinalize(this);
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if (_disposed) return;
        _disposed = true;
        await _file.WriteAsync(Encoding.UTF8.GetBytes(_buffer.ToString())).ConfigureAwait(false);
        await _file.DisposeAsync().ConfigureAwait(false);
    }

    public void Dispose()
    {
        Dispose(disposing: true);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (_disposed || !disposing) return;
        _disposed = true;
        _file.Write(Encoding.UTF8.GetBytes(_buffer.ToString()));   // synchronous fallback
        _file.Dispose();
    }
}

public sealed class AsyncOnlyExporter : IAsyncDisposable
{
    public ValueTask DisposeAsync() => ValueTask.CompletedTask;
}