System.DisposableObject 10.1.0

System.DisposableObject

System.DisposableObject is a lightweight .NET base-class library that implements the Dispose Pattern so you don't have to. Inherit from one of two abstract base classes and override a pair of simple hook methods — the boilerplate is handled for you.

• DisposableObject — implements IDisposable with a full finalizer, double-dispose guard, and re-entrancy guard.
• AsyncDisposableObject — extends DisposableObject with IAsyncDisposable, enabling await using while keeping synchronous callers working.

Table of Contents

1. Installation
2. Quick Start
   • Synchronous disposal — DisposableObject
   • Async disposal — AsyncDisposableObject
3. API Reference
   • DisposableObject
   • AsyncDisposableObject
4. Advanced Usage
   • Guarding methods against use after disposal
   • Debugging — detect objects not disposed properly
   • Custom class name in diagnostic messages
5. How Disposal Works
6. Contributing
7. License
8. References

Installation

Install the package from NuGet:

dotnet add package System.DisposableObject

Or via the Package Manager Console in Visual Studio:

Install-Package System.DisposableObject

Quick Start

Synchronous disposal — DisposableObject

Inherit from DisposableObject and override whichever hook methods your class needs.

using System;

public class DatabaseConnection : DisposableObject
{
    private SqlConnection _connection;

    public DatabaseConnection(string connectionString)
    {
        _connection = new SqlConnection(connectionString);
        _connection.Open();
    }

    protected override void OnDisposeManagedObjects()
    {
        // Dispose CLR-managed objects (objects that implement IDisposable).
        _connection?.Dispose();
        _connection = null;
    }

    protected override void OnDisposeUnmanagedObjects()
    {
        // Release native handles, file descriptors, COM objects, etc.
        // Do NOT reference other .NET objects here — this method can be
        // called by the GC finalizer after managed objects have been collected.
    }
}

Use it with a using statement (recommended):

using (var db = new DatabaseConnection(connectionString))
{
    // Work with db here.
} // OnDisposeManagedObjects() and OnDisposeUnmanagedObjects() are called here.

Or call Dispose() explicitly:

var db = new DatabaseConnection(connectionString);
// ... use db ...
db.Dispose();

Async disposal — AsyncDisposableObject

Inherit from AsyncDisposableObject when your class wraps async-capable resources or when callers may use await using.

using System;
using System.Threading.Tasks;

public class AsyncDatabaseConnection : AsyncDisposableObject
{
    private SqlConnection _connection;

    public AsyncDatabaseConnection(string connectionString)
    {
        _connection = new SqlConnection(connectionString);
    }

    protected override void OnDisposeManagedObjects()
    {
        // Synchronous cleanup of managed resources.
        _connection?.Dispose();
        _connection = null;
    }

    protected override void OnDisposeUnmanagedObjects()
    {
        // Native resource cleanup.
    }
}

Use it with await using (recommended for async code):

await using (var db = new AsyncDatabaseConnection(connectionString))
{
    // Work with db here.
} // DisposeAsync() → Dispose() → hooks called here.

Synchronous callers still work as before:

using (var db = new AsyncDatabaseConnection(connectionString))
{
    // Works fine — AsyncDisposableObject inherits DisposableObject.
}

API Reference

DisposableObject

Namespace: System
Assembly: System.DisposableObject
Inherits: System.Dynamic.DynamicObject
Implements: IDisposable

DisposableObject is abstract. You cannot instantiate it directly; create a class that inherits from it.

Protected properties

Public methods

Protected virtual methods (hooks)

Override any of the following in your subclass:

AsyncDisposableObject

Namespace: System
Assembly: System.DisposableObject
Inherits: DisposableObject
Implements: IDisposable, IAsyncDisposable

Adds a DisposeAsync() method on top of everything provided by DisposableObject. The hook methods (OnDisposeManagedObjects, OnDisposeUnmanagedObjects) are identical — there is no separate async hook.

Public methods (in addition to DisposableObject)

Advanced Usage

Guarding methods against use after disposal

Call AccessMethod() at the start of any public or internal method in your subclass to ensure the object has not been disposed:

public class MyResource : DisposableObject
{
    private byte[] _buffer = new byte[1024];

    public int ReadData(byte[] destination, int count)
    {
        // Throws ObjectDisposedException if Dispose() was already called.
        this.AccessMethod();

        // ... perform the read ...
        return count;
    }

    protected override void OnDisposeManagedObjects()
    {
        _buffer = null;
    }
}

After Dispose() is called, any subsequent call to ReadData will throw ObjectDisposedException with the name of the type.

Debugging — detect objects not disposed properly

Enable AssertWhenNotDisposed in your subclass constructor during development to catch objects that are garbage-collected without an explicit Dispose():

public class LeakDetectingResource : DisposableObject
{
    public LeakDetectingResource()
    {
        // Enable only in DEBUG builds to help catch disposal leaks.
#if DEBUG
        this.AssertWhenNotDisposed = true;
#endif
    }

    protected override void OnDisposeManagedObjects() { /* ... */ }
}

When AssertWhenNotDisposed is true and the GC finalizer runs without a prior Dispose():

• If OnNotDisposedProperly() returns false (the default), a Trace.Assert fires.
• If OnNotDisposedProperly() returns true, a Trace.TraceWarning is emitted instead and no assertion fires.

Custom class name in diagnostic messages

Override OnGetClassName() to provide a more readable name in trace/assert messages:

public class MyService : DisposableObject
{
    protected override string OnGetClassName() => nameof(MyService);

    protected override void OnDisposeManagedObjects() { /* ... */ }
}

How Disposal Works

The diagram below shows the code paths during object lifetime.

Explicit call:  obj.Dispose()
                    │
                    ▼
        DisposableObject.Dispose()
                    │  ── calls GC.SuppressFinalize(this)
                    ▼
        DisposableObject.Dispose(disposing: true)
                    ├─► OnDisposeManagedObjects()    ← override in subclass
                    └─► OnDisposeUnmanagedObjects()  ← override in subclass

GC finalizer:   ~DisposableObject()
                    │  (only reached if Dispose() was never called)
                    ▼
        DisposableObject.Dispose(disposing: false)
                    └─► OnDisposeUnmanagedObjects()  ← managed objects must NOT be touched

Async call:     await obj.DisposeAsync()
                    │
                    ▼
        AsyncDisposableObject.DisposeAsync()
                    │  ── delegates to synchronous Dispose()
                    └─► (same flow as explicit synchronous call above)

Key guarantees provided by the base classes:

Contributing

Contributions are welcome. Please open an issue or submit a pull request on GitHub.

License

This library is distributed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later). See LICENSE for the full text.

References

1. IDisposable Interface — Microsoft Docs
2. Implementing a Dispose method — Microsoft Docs
3. Implementing a DisposeAsync method — Microsoft Docs
4. IAsyncDisposable Interface — Microsoft Docs