Implement a DisposeAsync method

Article
05/12/2023

The System.IAsyncDisposable interface was introduced as part of C# 8.0. You implement the IAsyncDisposable.DisposeAsync() method when you need to perform resource cleanup, just as you would when implementing a Dispose method. One of the key differences, however, is that this implementation allows for asynchronous cleanup operations. The DisposeAsync() returns a ValueTask that represents the asynchronous disposal operation.

It's typical when implementing the IAsyncDisposable interface that classes also implement the IDisposable interface. A good implementation pattern of the IAsyncDisposable interface is to be prepared for either synchronous or asynchronous disposal, however, it's not a requirement. If no synchronous disposable of your class is possible, having only IAsyncDisposable is acceptable. All of the guidance for implementing the disposal pattern also applies to the asynchronous implementation. This article assumes that you're already familiar with how to implement a Dispose method.

Caution

If you implement the IAsyncDisposable interface but not the IDisposable interface, your app can potentially leak resources. If a class implements IAsyncDisposable, but not IDisposable, and a consumer only calls Dispose, your implementation would never call DisposeAsync. This would result in a resource leak.

Tip

With regard to dependency injection, when registering services in an IServiceCollection, the service lifetime is managed implicitly on your behalf. The IServiceProvider and corresponding IHost orchestrate resource cleanup. Specifically, implementations of IDisposable and IAsyncDisposable are properly disposed at the end of their specified lifetime.

For more information, see Dependency injection in .NET.

Explore `DisposeAsync` and `DisposeAsyncCore` methods

The IAsyncDisposable interface declares a single parameterless method, DisposeAsync(). Any nonsealed class should define a DisposeAsyncCore() method that also returns a ValueTask.

A public IAsyncDisposable.DisposeAsync() implementation that has no parameters.
A protected virtual ValueTask DisposeAsyncCore() method whose signature is:
```
protected virtual ValueTask DisposeAsyncCore()
{
}
```

The `DisposeAsync` method

The public parameterless DisposeAsync() method is called implicitly in an await using statement, and its purpose is to free unmanaged resources, perform general cleanup, and to indicate that the finalizer, if one is present, need not run. Freeing the memory associated with a managed object is always the domain of the garbage collector. Because of this, it has a standard implementation:

public async ValueTask DisposeAsync()
{
    // Perform async cleanup.
    await DisposeAsyncCore();

    // Dispose of unmanaged resources.
    Dispose(false);

    // Suppress finalization.
    GC.SuppressFinalize(this);
}

Note

One primary difference in the async dispose pattern compared to the dispose pattern, is that the call from DisposeAsync() to the Dispose(bool) overload method is given false as an argument. When implementing the IDisposable.Dispose() method, however, true is passed instead. This helps ensure functional equivalence with the synchronous dispose pattern, and further ensures that finalizer code paths still get invoked. In other words, the DisposeAsyncCore() method will dispose of managed resources asynchronously, so you don't want to dispose of them synchronously as well. Therefore, call Dispose(false) instead of Dispose(true).

The `DisposeAsyncCore` method

The DisposeAsyncCore() method is intended to perform the asynchronous cleanup of managed resources or for cascading calls to DisposeAsync(). It encapsulates the common asynchronous cleanup operations when a subclass inherits a base class that is an implementation of IAsyncDisposable. The DisposeAsyncCore() method is virtual so that derived classes can define custom cleanup in their overrides.

Tip

If an implementation of IAsyncDisposable is sealed, the DisposeAsyncCore() method is not needed, and the asynchronous cleanup can be performed directly in the IAsyncDisposable.DisposeAsync() method.

Implement the async dispose pattern

All nonsealed classes should be considered a potential base class, because they could be inherited. If you implement the async dispose pattern for any potential base class, you must provide the protected virtual ValueTask DisposeAsyncCore() method. Some of the following examples use a NoopAsyncDisposable class that is defined as follows:

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

Here's an example implementation of the async dispose pattern that uses the NoopAsyncDisposable type. The type implements DisposeAsync by returning ValueTask.CompletedTask.

public class ExampleAsyncDisposable : IAsyncDisposable
{
    private IAsyncDisposable? _example;

    public ExampleAsyncDisposable() =>
        _example = new NoopAsyncDisposable();

    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);

        GC.SuppressFinalize(this);
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if (_example is not null)
        {
            await _example.DisposeAsync().ConfigureAwait(false);
        }

        _example = null;
    }
}

In the preceding example:

The ExampleAsyncDisposable is a nonsealed class that implements the IAsyncDisposable interface.
It contains a private IAsyncDisposable field, _example, that's initialized in the constructor.
The DisposeAsync method delegates to the DisposeAsyncCore method and calls GC.SuppressFinalize to notify the garbage collector that the finalizer doesn't have to run.
It contains a DisposeAsyncCore() method that calls the _example.DisposeAsync() method, and sets the field to null.
The DisposeAsyncCore() method is virtual, which allows subclasses to override it with custom behavior.

Sealed alternative async dispose pattern

If your implementing class can be sealed, you can implement the async dispose pattern by overriding the IAsyncDisposable.DisposeAsync() method. The following example shows how to implement the async dispose pattern for a sealed class:

public sealed class SealedExampleAsyncDisposable : IAsyncDisposable
{
    private readonly IAsyncDisposable _example;

    public SealedExampleAsyncDisposable() =>
        _example = new NoopAsyncDisposable();

    public ValueTask DisposeAsync() => _example.DisposeAsync();
}

In the preceding example:

The SealedExampleAsyncDisposable is a sealed class that implements the IAsyncDisposable interface.
The containing _example field is readonly and is initialized in the constructor.
The DisposeAsync method calls the _example.DisposeAsync() method, implementing the pattern through the containing field (cascading disposal).

Implement both dispose and async dispose patterns

You may need to implement both the IDisposable and IAsyncDisposable interfaces, especially when your class scope contains instances of these implementations. Doing so ensures that you can properly cascade clean up calls. Here's an example class that implements both interfaces and demonstrates the proper guidance for cleanup.

class ExampleConjunctiveDisposableusing : IDisposable, IAsyncDisposable
{
    IDisposable? _disposableResource = new MemoryStream();
    IAsyncDisposable? _asyncDisposableResource = new MemoryStream();

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

    public async ValueTask DisposeAsync()
    {
        await DisposeAsyncCore().ConfigureAwait(false);

        Dispose(disposing: false);
        GC.SuppressFinalize(this);
    }

    protected virtual void Dispose(bool disposing)
    {
        if (disposing)
        {
            _disposableResource?.Dispose();
            _disposableResource = null;

            if (_asyncDisposableResource is IDisposable disposable)
            {
                disposable.Dispose();
                _asyncDisposableResource = null;
            }
        }
    }

    protected virtual async ValueTask DisposeAsyncCore()
    {
        if (_asyncDisposableResource is not null)
        {
            await _asyncDisposableResource.DisposeAsync().ConfigureAwait(false);
        }

        if (_disposableResource is IAsyncDisposable disposable)
        {
            await disposable.DisposeAsync().ConfigureAwait(false);
        }
        else
        {
            _disposableResource?.Dispose();
        }

        _asyncDisposableResource = null;
        _disposableResource = null;
    }
}

The IDisposable.Dispose() and IAsyncDisposable.DisposeAsync() implementations are both simple boilerplate code.

In the Dispose(bool) overload method, the IDisposable instance is conditionally disposed of if it isn't null. The IAsyncDisposable instance is cast as IDisposable, and if it's also not null, it's disposed of as well. Both instances are then assigned to null.

With the DisposeAsyncCore() method, the same logical approach is followed. If the IAsyncDisposable instance isn't null, its call to DisposeAsync().ConfigureAwait(false) is awaited. If the IDisposable instance is also an implementation of IAsyncDisposable, it's also disposed of asynchronously. Both instances are then assigned to null.

Each implementation strives to dispose of all possible disposable objects. This ensures that the cleanup is cascaded properly.

Using async disposable

To properly consume an object that implements the IAsyncDisposable interface, you use the await and using keywords together. Consider the following example, where the ExampleAsyncDisposable class is instantiated and then wrapped in an await using statement.

class ExampleConfigureAwaitProgram
{
    static async Task Main()
    {
        var exampleAsyncDisposable = new ExampleAsyncDisposable();
        await using (exampleAsyncDisposable.ConfigureAwait(false))
        {
            // Interact with the exampleAsyncDisposable instance.
        }

        Console.ReadLine();
    }
}

Important

Use the ConfigureAwait(IAsyncDisposable, Boolean) extension method of the IAsyncDisposable interface to configure how the continuation of the task is marshalled on its original context or scheduler. For more information on ConfigureAwait, see ConfigureAwait FAQ.

For situations where the usage of ConfigureAwait isn't needed, the await using statement could be simplified as follows:

class ExampleUsingStatementProgram
{
    static async Task Main()
    {
        await using (var exampleAsyncDisposable = new ExampleAsyncDisposable())
        {
            // Interact with the exampleAsyncDisposable instance.
        }

        Console.ReadLine();
    }
}

Furthermore, it could be written to use the implicit scoping of a using declaration.

class ExampleUsingDeclarationProgram
{
    static async Task Main()
    {
        await using var exampleAsyncDisposable = new ExampleAsyncDisposable();

        // Interact with the exampleAsyncDisposable instance.

        Console.ReadLine();
    }
}

Multiple await keywords in a single line

Sometimes the await keyword may appear multiple times within a single line. For example, consider the following code:

await using var transaction = await context.Database.BeginTransactionAsync(token);

In the preceding example:

The BeginTransactionAsync method is awaited.
The return type is DbTransaction, which implements IAsyncDisposable.
The transaction is used asynchronously, and also awaited.

Stacked usings

In situations where you create and use multiple objects that implement IAsyncDisposable, it's possible that stacking await using statements with ConfigureAwait could prevent calls to DisposeAsync() in errant conditions. To ensure that DisposeAsync() is always called, you should avoid stacking. The following three code examples show acceptable patterns to use instead.

Acceptable pattern one


class ExampleOneProgram
{
    static async Task Main()
    {
        var objOne = new ExampleAsyncDisposable();
        await using (objOne.ConfigureAwait(false))
        {
            // Interact with the objOne instance.

            var objTwo = new ExampleAsyncDisposable();
            await using (objTwo.ConfigureAwait(false))
            {
                // Interact with the objOne and/or objTwo instance(s).
            }
        }

        Console.ReadLine();
    }
}

In the preceding example, each asynchronous clean-up operation is explicitly scoped under the await using block. The outer scope follows how objOne sets its braces, enclosing objTwo, as such objTwo is disposed first, followed by objOne. Both IAsyncDisposable instances have their DisposeAsync() method awaited, so each instance performs its asynchronous clean-up operation. The calls are nested, not stacked.

Acceptable pattern two

class ExampleTwoProgram
{
    static async Task Main()
    {
        var objOne = new ExampleAsyncDisposable();
        await using (objOne.ConfigureAwait(false))
        {
            // Interact with the objOne instance.
        }

        var objTwo = new ExampleAsyncDisposable();
        await using (objTwo.ConfigureAwait(false))
        {
            // Interact with the objTwo instance.
        }

        Console.ReadLine();
    }
}

In the preceding example, each asynchronous clean-up operation is explicitly scoped under the await using block. At the end of each block, the corresponding IAsyncDisposable instance has its DisposeAsync() method awaited, thus performing its asynchronous clean-up operation. The calls are sequential, not stacked. In this scenario objOne is disposed first, then objTwo is disposed.

Acceptable pattern three

class ExampleThreeProgram
{
    static async Task Main()
    {
        var objOne = new ExampleAsyncDisposable();
        await using var ignored1 = objOne.ConfigureAwait(false);

        var objTwo = new ExampleAsyncDisposable();
        await using var ignored2 = objTwo.ConfigureAwait(false);

        // Interact with objOne and/or objTwo instance(s).

        Console.ReadLine();
    }
}

In the preceding example, each asynchronous clean-up operation is implicitly scoped with the containing method body. At the end of the enclosing block, the IAsyncDisposable instances perform their asynchronous clean-up operations. This example runs in reverse order from which they were declared, meaning that objTwo is disposed before objOne.

Unacceptable pattern

The highlighted lines in the following code show what it means to have "stacked usings". If an exception is thrown from the AnotherAsyncDisposable constructor, neither object is properly disposed of. The variable objTwo is never assigned because the constructor didn't complete successfully. As a result, the constructor for AnotherAsyncDisposable is responsible for disposing any resources allocated before it throws an exception. If the ExampleAsyncDisposable type has a finalizer, it's eligible for finalization.

class DoNotDoThisProgram
{
    static async Task Main()
    {
        var objOne = new ExampleAsyncDisposable();
        // Exception thrown on .ctor
        var objTwo = new AnotherAsyncDisposable();

        await using (objOne.ConfigureAwait(false))
        await using (objTwo.ConfigureAwait(false))
        {
            // Neither object has its DisposeAsync called.
        }

        Console.ReadLine();
    }
}

Tip

Avoid this pattern as it could lead to unexpected behavior. If you use one of the acceptable patterns, the problem of undisposed objects is non-existent. The clean-up operations are correctly performed when using statements aren't stacked.

Implement a DisposeAsync method

Explore `DisposeAsync` and `DisposeAsyncCore` methods

The `DisposeAsync` method

The `DisposeAsyncCore` method

Implement the async dispose pattern

Sealed alternative async dispose pattern

Implement both dispose and async dispose patterns

Using async disposable

Multiple await keywords in a single line

Stacked usings

Acceptable pattern one

Acceptable pattern two

Acceptable pattern three

Unacceptable pattern

See also

Feedback

Additional resources

Implement a DisposeAsync method

Explore DisposeAsync and DisposeAsyncCore methods

The DisposeAsync method

The DisposeAsyncCore method

Implement the async dispose pattern

Sealed alternative async dispose pattern

Implement both dispose and async dispose patterns

Using async disposable

Multiple await keywords in a single line

Stacked usings

Acceptable pattern one

Acceptable pattern two

Acceptable pattern three

Unacceptable pattern

See also

Feedback

Additional resources

Explore `DisposeAsync` and `DisposeAsyncCore` methods

The `DisposeAsync` method

The `DisposeAsyncCore` method