פקודת using ב-C#: IDisposable, Dispose ו-using var

יש אובייקטים שמחזיקים משאבים שאוסף הזבל לא מנהל: קבצים פתוחים, sockets ברשת, חיבורים למסד נתונים, ידיות של מערכת ההפעלה. הם מממשים IDisposable, ומשחררים את המשאב בקריאה ל-Dispose(). פקודת using קוראת לה בשבילכם בנקודה קבועה, גם אם נזרקת חריגה.

העמוד הזה עוסק בפקודת using. השורות using System; בראש קובץ הן תכונה אחרת, הנחיית using, שמייבאת מרחב שמות.

בלוק using

using (declaration) { body } יוצרת את האובייקט, מריצה את הגוף, ואז קוראת ל-Dispose. מחלקה קטנה שמדפיסה מתוך Dispose מראה בדיוק מתי זה קורה:

using System;

class Connection : IDisposable
{
    private readonly string name;

    public Connection(string name)
    {
        this.name = name;
        Console.WriteLine("open " + name);
    }

    public void Send(string msg)
    {
        Console.WriteLine(name + " sends " + msg);
    }

    public void Dispose()
    {
        Console.WriteLine("close " + name);
    }
}

class Program
{
    static void Main()
    {
        using (var db = new Connection("db"))
        {
            db.Send("SELECT 1");
        } // db.Dispose() runs here

        try
        {
            using (var api = new Connection("api"))
            {
                api.Send("GET /orders");
                throw new InvalidOperationException();
            } // api.Dispose() still runs, before the catch
        }
        catch (InvalidOperationException)
        {
            Console.WriteLine("error handled");
        }
    }
}

פלט:

open db
db sends SELECT 1
close db
open api
api sends GET /orders
close api
error handled

הבלוק השני זורק, ו-"close api" עדיין מודפס, לפני שה-catch מטפל בחריגה. ההבטחה הזו היא הסיבה להשתמש ב-using במקום לקרוא ל-Dispose() בעצמכם בשורה האחרונה: קריאה ידנית מדולגת על ידי כל חריגה שנזרקת לפניה.

למה using מתקמפלת

הקומפיילר פורש בלוק using ל-try/finally. שתי הצורות האלה שקולות:

using (var writer = new StreamWriter("log.txt"))
{
    writer.WriteLine("started");
}

// is compiled as:
{
    var writer = new StreamWriter("log.txt");
    try
    {
        writer.WriteLine("started");
    }
    finally
    {
        if (writer != null) ((IDisposable)writer).Dispose();
    }
}

שלושה פרטים נובעים מהפרישה הזו. המשתנה מוגבל לטווח של הבלוק והוא לקריאה בלבד בתוכו (אי אפשר להשים מחדש ל-writer). האובייקט חייב לממש IDisposable, אחרת הקוד לא מתקמפל. וערך null מותר: Dispose פשוט מדולג, וזה שימושי כשפונקציית factory עלולה לא להחזיר כלום.

קבצים וזרמים

מחלקות של קבצים וזרמים הן המקרה היומיומי. StreamWriter שומר טקסט בחוצץ בזיכרון, ו-Dispose כותב את החוצץ לדיסק וסוגר את ידית הקובץ:

using System;
using System.IO;

class Program
{
    static void Main()
    {
        string path = Path.Combine(Path.GetTempPath(), "orders.csv");

        using (var writer = new StreamWriter(path))
        {
            writer.WriteLine("id,total");
            writer.WriteLine("1001,59.90");
            writer.WriteLine("1002,12.50");
        } // flushed and closed here

        using (var reader = new StreamReader(path))
        {
            string line;
            while ((line = reader.ReadLine()) != null)
            {
                Console.WriteLine(line);
            }
        }

        File.Delete(path); // allowed: nothing holds the file open
    }
}

פלט:

id,total
1001,59.90
1002,12.50

בלי Dispose, השורות האחרונות של ה-writer עלולות עדיין לשבת בחוצץ שלו, וב-Windows הידית הפתוחה מונעת מתוכניות אחרות (ומה-File.Delete הבא שלכם) לגעת בקובץ. מתודות עזר כמו File.WriteAllText ו-File.ReadAllLines פותחות ומשחררות בעצמן, כך שהן לא צריכות using. ראו files להרחבה.

כמה משאבים: סדר השחרור

ערמו פקודות using בלי סוגריים מסולסלים ביניהן כדי לפתוח כמה משאבים בבלוק אחד. הם משתחררים בסדר הפוך לסדר היצירה:

using System;

class Resource : IDisposable
{
    private readonly string name;
    public Resource(string name) { this.name = name; Console.WriteLine("acquire " + name); }
    public void Dispose() { Console.WriteLine("release " + name); }
}

class Program
{
    static void Main()
    {
        using (var file = new Resource("file"))
        using (var buffer = new Resource("buffer"))
        using (var writer = new Resource("writer"))
        {
            Console.WriteLine("working");
        }

        // Several of the same type can share one statement:
        using (Resource a = new Resource("a"), b = new Resource("b"))
        {
            Console.WriteLine("both open");
        }
    }
}

פלט:

acquire file
acquire buffer
acquire writer
working
release writer
release buffer
release file
acquire a
acquire b
both open
release b
release a

סדר הפוך הוא מה שמשאבים בשכבות צריכים: writer עוטף buffer שעוטף קובץ, כך שה-writer חייב לרוקן את עצמו לתוך ה-buffer לפני שה-buffer כותב לקובץ, ולפני שהקובץ נסגר.

הצהרת ה-using (C# 8)

C# 8 הוסיפה צורה בלי סוגריים מסולסלים. המשתנה משתחרר כשהטווח העוטף מסתיים, בדרך כלל בסוף המתודה:

static void ExportReport(string path, IEnumerable<string> rows)
{
    using var writer = new StreamWriter(path);
    writer.WriteLine("Report");

    foreach (string row in rows)
    {
        writer.WriteLine(row);
    }
} // writer.Dispose() runs here, at the end of the method

היא חוסכת רמת הזחה אחת, וזה מצטבר כשמתודה משתמשת בשניים או שלושה משאבים. כלל סדר השחרור זהה: הצהרות באותו טווח משתחררות בסדר הפוך. המחיר הוא שהמשאב נשאר פתוח עד שהטווח מסתיים, כך שכשקובץ צריך להיסגר לפני שהמתודה עושה עוד עבודה, השאירו את צורת הבלוק או שימו את ההצהרה בבלוק { } משלה.

לאובייקטים שהניקוי שלהם אסינכרוני (IAsyncDisposable, כמו הרבה חיבורים למסדי נתונים וזרמים), ב-C# 8 יש גם await using, שמבצעת await על DisposeAsync() באותו מקום.

מימוש IDisposable במחלקה שלכם

ממשו IDisposable כשהמחלקה שלכם מחזיקה בבעלותה משהו שצריך שחרור (היא יצרה זרם, טיימר, חיבור) ולכן חייבת לשחרר אותו בתורה. במקרה הנפוץ, זו מתודה קצרה:

using System;
using System.IO;

class AuditLog : IDisposable
{
    private readonly StringWriter output = new StringWriter(); // an owned IDisposable
    private bool disposed;
    private int count;

    public void Write(string entry)
    {
        if (disposed) throw new ObjectDisposedException(nameof(AuditLog));
        output.WriteLine(++count + ". " + entry);
    }

    public string Contents => output.ToString();

    public void Dispose()
    {
        if (disposed) return; // calling Dispose twice must be harmless
        output.Dispose();
        disposed = true;
        Console.WriteLine("AuditLog disposed");
    }
}

class Program
{
    static void Main()
    {
        var log = new AuditLog();
        using (log)
        {
            log.Write("user ana logged in");
            log.Write("order 1001 created");
            Console.Write(log.Contents);
        }

        log.Dispose(); // second call: no effect

        try
        {
            log.Write("too late");
        }
        catch (ObjectDisposedException e)
        {
            Console.WriteLine("Caught " + e.GetType().Name);
        }
    }
}

פלט:

1. user ana logged in
2. order 1001 created
AuditLog disposed
Caught ObjectDisposedException

הכללים שהקוד הזה עוקב אחריהם: Dispose משחררת את כל מה שהאובייקט מחזיק בבעלותו; קריאה לה יותר מפעם אחת לא עושה כלום בפעם השנייה; ושימוש באובייקט אחרי השחרור זורק ObjectDisposedException. using (log) מראה גם שהבלוק יכול לקבל משתנה קיים במקום הצהרה.

"תבנית ה-dispose" הארוכה יותר, עם מתודה protected virtual void Dispose(bool disposing) ו-finalizer, נחוצה רק כשמחלקה מחזיקה ישירות ידית לא מנוהלת (מצביע גולמי מקוד native). ב-.NET מודרני, עטפו ידיות כאלה במחלקה שיורשת מ-SafeHandle במקום זאת, והגרסה הפשוטה שלמעלה היא כל מה שהמחלקה שלכם צריכה.

טעויות נפוצות

• החזרה של אובייקט שנוצר בבלוק using. הוא משתחרר כשהבלוק מסתיים, כך שהקורא מקבל זרם סגור. החזירו את הנתונים, או תנו לקורא להחזיק את ה-using.
• שכחה של using על זרמים ו-writers. נתונים שבחוצץ יכולים ללכת לאיבוד וקבצים נשארים נעולים.
• שחרור של אובייקט משותף. שחררו רק את מה ששייך לכם. HttpClient ארוך חיים, למשל, נועד להיות משותף ולשימוש חוזר, לא להיווצר ולהשתחרר בכל בקשה.
• שימוש באובייקט אחרי הבלוק. מתודות על אובייקט משוחרר זורקות ObjectDisposedException.
• הסתמכות על אוסף הזבל. הוא משחרר זיכרון, לא קבצים או sockets, ואף פעם לא קורא ל-Dispose.