A Brief Discussion on the Dispose Pattern and the using Statement

Using the using statement to release IDisposable objects is a fundamental operation in .NET programming. I have explained this to clients before, but upon reflection, while I know how to use it, I may not fully grasp some of the finer details. Therefore, I decided to take notes while researching to see if there are any gaps in my understanding.

The Dispose Pattern

Unmanaged Resources

Managed resources refer to resources managed by the .NET runtime's Common Language Runtime (CLR), where memory management is handled automatically by the Garbage Collector (GC), requiring no manual release by the developer. Unmanaged resources, such as database connections or file access, must be released through specific means. Although .NET can track objects that encapsulate unmanaged resources, you must manually release the unmanaged resources because the GC cannot automatically handle their release. For specific details, please refer to "Cleaning up unmanaged resources".

There are two ways to release unmanaged resources:

• Implementing the Dispose Pattern: Implement the IDisposable interface and release unmanaged resources within the Dispose() method.
• Declaring a Finalizer: Previously known as a destructor, it cannot be called manually but is automatically invoked during garbage collection (GC) to release unmanaged resources. However, when implementing IDisposable, you should prioritize using the Dispose method to release resources. For more details, refer to the article "Finalizers (C# Programming Guide)".

Implementation Example

public class ResourceHandle : IDisposable {
    // Flag to prevent redundant disposal
    private bool disposed = false;
    // Simulate unmanaged resource
    private IntPtr unmanagedResource;
    // Simulate managed resource that internally contains unmanaged resources
    private ManagedResource managedResource;

    public ResourceHandle() {
        unmanagedResource = IntPtr.Zero; // Initialization demonstration, should allocate resources in practice
        managedResource = new ManagedResource();
    }

    // Implement the Dispose method of the IDisposable interface
    public void Dispose() {
        // Release unmanaged and managed resources
        Dispose(true);
        // Prevent the GC from calling the finalizer again since resources are already released
        GC.SuppressFinalize(this);
    }

    // Protected virtual method for subclasses to override
    protected virtual void Dispose(bool disposing) {
        if (!disposed) {
            if (disposing) {
                // Release managed resources
                managedResource?.Dispose();
                managedResource = null;
            }

            // Release unmanaged resources
            if (unmanagedResource != IntPtr.Zero) {
                // Assume this is a method that releases unmanaged resources
                FreeUnmanagedResource(unmanagedResource);
                unmanagedResource = IntPtr.Zero;
            }

            disposed = true;
        }
    }

    // Finalizer
    ~ResourceHandle() {
        // The finalizer is called automatically during garbage collection to release unmanaged resources.
        // Managed resources are handled automatically by the GC, so no need to process them here.
        Dispose(false);
    }
}

For extended practices, you can refer to the MSDN example "Implementing a Dispose method".

Asynchronous Dispose Pattern

The IAsyncDisposable interface was added in .NET Core 3.0. I only learned about this interface while writing this article, so my understanding is not yet deep, and I will keep it brief. I have extracted what I consider important points from "Implementing a DisposeAsync method".

1. It is generally recommended to implement IDisposable when implementing IAsyncDisposable. While not strictly required, it is the recommended best practice. The reason will be explained after reviewing the example.
2. In ASP.NET Core, most objects are injected using Dependency Injection (DI). If an object created via DI implements IAsyncDisposable or IDisposable, DisposeAsync() or Dispose() will be called at the end of its lifecycle to release unmanaged resources. According to the RequestServicesFeature code, when an object implements both, DisposeAsync() is prioritized.

I have adapted the code directly from MSDN for the following example.

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 DisposeCoreAsync().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;
            }

            // If there are unmanaged resources to release, do it here
        }
    }

    protected virtual async ValueTask DisposeCoreAsync() {
        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;
    }
}

There are a few points to note in this example:

• Implementation of DisposeAsync(): DisposeAsync() calls DisposeAsync(bool disposing) with false. This is because both Dispose(bool disposing) and DisposeCoreAsync() handle objects that can be disposed synchronously and asynchronously; calling DisposeAsync(bool disposing) is only intended to handle other unmanaged resources.

• Processing logic of Dispose(bool disposing): In the Dispose(bool disposing) method, the asynchronous DisposeCoreAsync method is typically not called to avoid the possibility of deadlocks between synchronous and asynchronous operations. Therefore, it only checks if IDisposable is implemented. If it is, Dispose() is called. This means that if the asynchronous object type does not implement IDisposable, the resource might not be released correctly.

• Reason for implementing IDisposable simultaneously: IAsyncDisposable is an interface added in .NET Core 3.0, primarily to support asynchronous resource release. However, some existing programs and resource management frameworks may have already implemented IDisposable before IAsyncDisposable existed. Consequently, these programs might only check if an object implements IDisposable and ignore IAsyncDisposable. Therefore, implementing IDisposable ensures compatibility in contexts that do not support asynchronous release, allowing resources to be released correctly.

• Purpose of ConfigureAwait(false): Regarding the purpose of ConfigureAwait(false), the MSDN article refers directly to the "ConfigureAwait FAQ". According to my understanding, ConfigureAwait(false) allows the program not to force a return to the original SynchronizationContext after an await operation completes. The SynchronizationContext could be a UI thread (like the main thread in a Windows application) or a Web request processing thread. This is typically used in background asynchronous processing when there is no need to return to the original context, thereby improving performance and avoiding unnecessary context switching or deadlocks. To be honest, I don't fully grasp it myself, so I recommend reading the original source.

Regarding when to use IAsyncDisposable, since I usually only handle objects containing unmanaged resources rather than directly manipulating unmanaged resources (in fact, I don't know how), and more and more objects in .NET containing unmanaged resources already implement IAsyncDisposable, I can implement IAsyncDisposable to improve performance when implementing the Dispose pattern involving these objects.

The using Statement

Basic Method for Ensuring Resource Release

When encountering objects that require management of unmanaged resources, to avoid forgetting to call Dispose(), a try...finally structure is usually used. This ensures that Dispose() is called regardless of whether an exception occurs. The following is a code example:

ResourceHandle handle;
try {
    handle = new ResourceHandle();
    // Perform other methods with handle
} finally {
    // Resources will be released regardless of whether an Exception occurs; can be simplified to handle?.Dispose();
    if (handle is not null) {
        handle.Dispose();
    }
}

When dealing with objects that implement IDisposable, you can use the using statement to automatically release resources. The compiler converts the using statement into a try...finally structure. This not only makes the code more concise but also reduces errors that might occur when manually managing resource release. The following is an example of using using:

using (ResourceHandle handle = new ResourceHandle()) {
    // Perform other methods with handle
}

Of course, if you need to handle Exceptions specifically, you might consider reverting to a try...catch...finally structure.

Nested using Statements

For multiple objects that need to be released, you can use nested using statements.

using (ResourceHandle handle1 = new ResourceHandle()) {
    using (ResourceHandle handle2 = new ResourceHandle()) {
        // Perform other methods with handle1 and handle2
    }
}

When there is no other code between using statements, it can be simplified as follows to avoid excessive indentation:

using (ResourceHandle handle1 = new ResourceHandle())
using (ResourceHandle handle2 = new ResourceHandle()) {
    // Perform other methods with handle1 and handle2
}

If the types are the same, you can combine multiple variables into a single using statement:

using (ResourceHandle handle1 = new ResourceHandle(), handle2 = new ResourceHandle()) {
    // Perform other methods with handle1 and handle2
}

C# 8.0 New Syntax

C# 8.0 introduced a more concise using syntax. This new syntax can be used within braces in a method or within an independent scope, automatically calling the Dispose() method when leaving the scope. An example is as follows:

{
    using ResourceHandle handle = new ResourceHandle();
    // handle
}

Asynchronous Processing

For objects that implement IAsyncDisposable, you can use await using. An example is as follows:

await using (AsyncDisposableObject resource = new AsyncDisposableObject()) {
    // Use the resource
}

// Or
{
    await using AsyncDisposableObject resource = new AsyncDisposableObject();
}

Change Log

• 2024-08-08 Initial version created.