‫راهنمای جامع مدیریت منابع و الگوی Dispose در سی‌شارپ

• دستگیره‌های فایل (File Handles)
• اتصالات پایگاه داده (Database Connections)
• سوکت‌های شبکه (Network Sockets)
• دستگیره‌های مربوط به API های سیستم‌عامل (مانند دستگیره‌های گرافیکی GDI+)

public class CustomerRepository : IDisposable
{
    private bool _disposed = false;
    private readonly NpgsqlConnection _connection;

    public CustomerRepository(string connectionString)
    {
        _connection = new NpgsqlConnection(connectionString);
        _connection.Open();
    }
    
    // متدهایی که از اتصال پایگاه داده استفاده می‌کنند...
    
    public void Dispose()
    {
        if (_disposed)
            return;
            
        _disposed = true;
        
        // فراخوانی متد Dispose برای آزادسازی اتصال پایگاه داده
        _connection.Dispose();
    }
}

• فراخوانی آبشاری (Cascading Dispose): کلاس CustomerRepository "مالک" شیء _connection است، بنابراین مسئول آزادسازی آن نیز هست. این کار را با فراخوانی _connection.Dispose() انجام می‌دهد.
• Idempotency (هم‌توانی): متد Dispose باید طوری نوشته شود که اگر چندین بار فراخوانی شد، خطایی رخ ندهد. فیلد _disposed دقیقاً همین کار را انجام می‌دهد و تضمین می‌کند که منطق آزادسازی منابع فقط یک بار اجرا شود.

// روش اول: بلوک using
using (var repository = new CustomerRepository(_connectionString))
{
    // از repository استفاده کنید...
} // در این نقطه متد repository.Dispose() به صورت خودکار فراخوانی می‌شود

// روش دوم: using declaration (از سی‌شارپ ۸ به بعد)
private Customer? FindCustomer(int id)
{
    using var repository = new CustomerRepository(_connectionString);
    return repository.Get(id);
} // متد Dispose در انتهای اسکوپ متد (قبل از return) فراخوانی می‌شود

نکته مهم: بلوک using در واقع یک "Syntax Sugar" برای یک بلوک try...finally است. کد بالا در عمل به صورت زیر کامپایل می‌شود که تضمین می‌کند Dispose همیشه اجرا شود:

var repository = new CustomerRepository(_connectionString);
try
{
    // ...
}
finally
{
    repository.Dispose();
}

• مسیر قطعی (Deterministic): توسط برنامه‌نویس با فراخوانی متد Dispose().
• مسیر غیرقطعی (Non-deterministic): توسط GC در زمانی نامشخص، در صورتی که برنامه‌نویس فراخوانی Dispose را فراموش کرده باشد.

using System.Runtime.InteropServices;
using System.ComponentModel;

public class UnmanagedFileHandler : IDisposable
{
    // اشاره‌گر به منبع مدیریت‌نشده
    private IntPtr _handle;
    // یک منبع مدیریت‌شده که خود IDisposable است
    private readonly MemoryStream _buffer;
    private bool _disposed = false;

    [DllImport("kernel32.dll", SetLastError = true)]
    private static extern bool CloseHandle(IntPtr hObject);
    
    // ... کد مربوط به دریافت handle از API ویندوز ...

    public UnmanagedFileHandler(string filePath)
    {
        // ... دریافت handle و تخصیص آن به _handle ...
        _buffer = new MemoryStream();
    }

    // 1. پیاده‌سازی عمومی متد Dispose
    public void Dispose()
    {
        Dispose(true);
        // به GC اطلاع می‌دهیم که دیگر نیازی به فراخوانی Finalizer نیست
        GC.SuppressFinalize(this);
    }
    
    // 2. پیاده‌سازی Finalizer (یا Destructor)
    ~UnmanagedFileHandler()
    {
        Dispose(false);
    }
    
    // 3. متد اصلی و مجازی برای آزادسازی منابع
    protected virtual void Dispose(bool disposing)
    {
        if (_disposed)
            return;

        if (disposing)
        {
            // اگر از طریق Dispose() فراخوانی شده، منابع مدیریت‌شده را هم آزاد کن
            _buffer.Dispose();
        }

        // همیشه منابع مدیریت‌نشده را آزاد کن (چه از Dispose و چه از Finalizer)
        if (_handle != IntPtr.Zero)
        {
            CloseHandle(_handle);
            _handle = IntPtr.Zero;
        }

        _disposed = true;
    }
}

• Dispose(bool disposing): این متد قلب الگو است. منطق اصلی آزادسازی در اینجاست.
• اگر disposing برابر true باشد: یعنی متد Dispose() به صورت دستی توسط کاربر فراخوانی شده است. در این حالت هم منابع مدیریت‌شده (مثل _buffer) و هم منابع مدیریت‌نشده (مثل _handle) باید آزاد شوند.
• اگر disposing برابر false باشد: یعنی متد توسط Finalizer (از طریق GC) فراخوانی شده است. در این حالت فقط باید منابع مدیریت‌نشده را آزاد کنیم. چرا؟ چون در این لحظه، GC در حال پاک‌سازی اشیاء است و ما نمی‌توانیم به وضعیت اشیاء مدیریت‌شده دیگر (مثل _buffer) اعتماد کنیم؛ ممکن است آن‌ها نیز قبلاً پاک شده باشند.
• Finalizer (~UnmanagedFileHandler()): این یک "بکاپ" یا "طناب نجات" است. اگر برنامه‌نویس فراموش کند Dispose را فراخوانی کند، GC قبل از حذف کامل شیء، این متد را اجرا می‌کند تا حداقل منابع حیاتی مدیریت‌نشده آزاد شوند.
• GC.SuppressFinalize(this): این یک بهینه‌سازی بسیار مهم است. وقتی ما Dispose را به صورت دستی فراخوانی می‌کنیم، تمام کارها به درستی انجام شده است. با این متد به GC می‌گوییم که دیگر نیازی نیست این شیء را در صف Finalization قرار دهد که این کار باعث می‌شود GC سریع‌تر حافظه را آزاد کند.

public class LogFileHandler : UnmanagedFileHandler
{
    private bool _disposed = false;
    private readonly MemoryStream _logBuffer;

    public LogFileHandler(string filePath) : base(filePath)
    {
        _logBuffer = new MemoryStream();
    }

    protected override void Dispose(bool disposing)
    {
        if (_disposed)
            return;

        if (disposing)
        {
            // 1. منابع کلاس فرزند را آزاد کن
            _logBuffer.Dispose();
        }

        _disposed = true;
        
        // 2. حتماً متد Dispose کلاس پدر را فراخوانی کن
        base.Dispose(disposing);
    }
}

public class CustomerRepository : IAsyncDisposable
{
    private readonly NpgsqlConnection _connection;
    // ...

    public async ValueTask DisposeAsync()
    {
        // عملیات پاک‌سازی ناهمزمان
        await _connection.DisposeAsync();
    }
}

await using (var repository = new CustomerRepository(_connectionString))
{
    // ...
} // متد DisposeAsync() به صورت خودکار فراخوانی و await می‌شود

• همیشه Idempotent باشید: با استفاده از یک فیلد _disposed مطمئن شوید که منطق Dispose فقط یک بار اجرا می‌شود.
• هرگز در Finalizer خطا پرتاب نکنید: بروز یک Exception در Finalizer می‌تواند منجر به خاتمه کل فرآیند برنامه شود. کد داخل Finalizer باید تا حد امکان دفاعی و بدون خطا باشد.
• فراخوانی‌های Dispose را آبشاری کنید: اگر کلاس شما مالک یک شیء IDisposable است، شما مسئول Dispose کردن آن هستید.
• از SafeHandle استفاده کنید: به جای پیاده‌سازی الگوی کامل و کار مستقیم با IntPtr، دات‌نت کلاس SafeHandle و مشتقات آن را ارائه می‌دهد. این کلاس‌ها یک Wrapper امن حول دستگیره‌های مدیریت‌نشده ایجاد می‌کنند و خودشان الگوی کامل Dispose را به درستی پیاده‌سازی کرده‌اند. در برنامه‌نویسی مدرن، استفاده از SafeHandle به جای پیاده‌سازی دستی Finalizer به شدت توصیه می‌شود. این کار کد شما را بسیار ساده‌تر و امن‌تر می‌کند.
• کلاس خود را sealed کنید: اگر قصد ندارید از کلاس IDisposable شما ارث‌بری شود، آن را با کلمه کلیدی sealed مشخص کنید. این کار به JIT Compiler اجازه بهینه‌سازی‌های بیشتری می‌دهد.