رمي الاستثناءات في C#: جمل الحراسة وتعابير throw والاستثناءات المخصصة

التقاط الاستثناءات نصف معالجة الأخطاء؛ والنصف الآخر رمي الاستثناء الصحيح. الاستثناء المختار جيدًا يخبر المستدعي بالضبط ما الخطأ وهل كان خطأه أم حالة البرنامج. تغطي هذه الصفحة جانب الرمي؛ وتغطي try catch المعالجة.

عبارة throw وجمل الحراسة

تأخذ throw كائن استثناء. يتوقف تنفيذ الدالة هناك، ويبحث الاستثناء عن معالج صعودًا في مكدّس الاستدعاءات. أشيع استخدام هو جملة الحراسة: فحوص في أعلى الدالة ترفض المدخلات غير الصالحة قبل أداء أي عمل.

using System;

class Account
{
    public decimal Balance { get; private set; }
    public bool Frozen { get; set; }

    public void Withdraw(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        if (Frozen)
            throw new InvalidOperationException("The account is frozen.");
        if (amount > Balance)
            throw new InvalidOperationException("Insufficient funds.");

        Balance -= amount;
    }

    public void Deposit(decimal amount)
    {
        if (amount <= 0)
            throw new ArgumentOutOfRangeException(nameof(amount), "Amount must be positive.");
        Balance += amount;
    }
}

class Program
{
    static void Main()
    {
        var acct = new Account();
        acct.Deposit(100m);

        try
        {
            acct.Withdraw(-5m);
        }
        catch (ArgumentOutOfRangeException e)
        {
            Console.WriteLine(e.GetType().Name + " for parameter '" + e.ParamName + "'");
        }

        acct.Frozen = true;
        try
        {
            acct.Withdraw(20m);
        }
        catch (InvalidOperationException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.Message);
        }

        Console.WriteLine("Balance: " + acct.Balance);
    }
}

المخرجات:

ArgumentOutOfRangeException for parameter 'amount'
InvalidOperationException: The account is frozen.
Balance: 100

تنتج nameof(amount) النص "amount" وتبقى صحيحة إن أُعيدت تسمية المعامل. تخزّنه استثناءات الوسائط في ParamName، الذي تستخدمه الأدوات والسجلات للإشارة إلى الوسيط السيئ.

تبقي جمل الحراسة بقية الدالة بسيطة: بعد الفحوص تستطيع الشيفرة افتراض مدخلات صالحة. وتفشل أيضًا في موضع الخطأ بدل ترك قيمة سيئة تنتقل وتسبّب NullReferenceException مربكًا بعد ثلاث دوال.

أي نوع استثناء ترمي

أعد استخدام نوع مدمج حين يصف الحالة؛ فالمستدعون يعرفون أصلًا كيف يعالجونه.

الخط الفاصل بين الصفوف الثلاثة الأولى وInvalidOperationException هو من يحتاج إلى تغيير شيء. يقول استثناء الوسيط "استدعِ هذا بشكل مختلف". ويقول InvalidOperationException "الاستدعاء سليم، لكن ليس الآن".

لا ترمِ Exception أو SystemException أو ApplicationException مباشرة: لا يستطيع المستدعون التقاطها دون التقاط كل شيء آخر أيضًا. ولا ترمِ NullReferenceException أو IndexOutOfRangeException أو StackOverflowException بنفسك أيضًا؛ فوقت التشغيل يحجزها للأخطاء البرمجية الفعلية.

تعابير throw

قبل C# 7 كانت throw عبارة فقط. ومنذ C# 7 يمكنها الظهور أيضًا كتعبير في ثلاثة أماكن، وهذا يحوّل الفحوص الشائعة إلى سطر واحد:

using System;

class Customer
{
    private readonly string name;
    private readonly string email;

    public Customer(string name, string email)
    {
        this.name = name ?? throw new ArgumentNullException(nameof(name));       // after ??
        this.email = email.Contains("@")
            ? email
            : throw new ArgumentException("Not an email address.", nameof(email)); // in ?:
    }

    public string Name => name;

    public string Nickname => throw new NotImplementedException();                // expression body

    public override string ToString() => name + " <" + email + ">";
}

class Program
{
    static void Main()
    {
        Console.WriteLine(new Customer("Ana", "ana@example.com"));

        try
        {
            new Customer(null, "x@example.com");
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine("Null: " + e.ParamName);
        }

        try
        {
            new Customer("Ben", "ben.example.com");
        }
        catch (ArgumentException e)
        {
            Console.WriteLine(e.GetType().Name + ": " + e.ParamName);
        }
    }
}

المخرجات:

Ana <ana@example.com>
Null: name
ArgumentException: email

لاحظ أن ArgumentNullException مشتق من ArgumentException، فبند catch (ArgumentException) موضوع أولًا سيلتقط حالة null أيضًا. ولهذا السبب نفسه يهمّ ترتيب بنود catch حين تعالج الاثنين.

ThrowIfNull وأخواتها (.NET 6 وما بعده)

تضيف .NET الحديثة دوال مساعدة ساكنة تكتب الفحص والرمي عنك، مع التقاط اسم المعامل تلقائيًا:

public void Ship(Order order, int quantity, string address)
{
    ArgumentNullException.ThrowIfNull(order);                   // .NET 6
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(quantity); // .NET 8
    ArgumentException.ThrowIfNullOrWhiteSpace(address);          // .NET 8
    ObjectDisposedException.ThrowIf(disposed, this);             // .NET 7

    // ...
}

تتصرف مثل if وthrow المكتوبتين يدويًا، وتبقي كل جملة حراسة في سطر واحد. وعلى الأهداف الأقدم اكتب شكل if المعروض سابقًا.

كتابة صنف استثناء مخصص

أنشئ نوع استثناء خاصًا بك حين يحتاج المستدعون إلى التقاط هذا الفشل المحدد بشكل منفصل، أو حين يحتاج المعالج إلى بيانات لا يستطيع نص الرسالة حملها جيدًا.

using System;

class InsufficientFundsException : Exception
{
    public decimal Balance { get; }
    public decimal Requested { get; }

    public InsufficientFundsException() { }

    public InsufficientFundsException(string message) : base(message) { }

    public InsufficientFundsException(string message, Exception inner) : base(message, inner) { }

    public InsufficientFundsException(decimal balance, decimal requested)
        : base("Cannot withdraw " + requested + " from a balance of " + balance + ".")
    {
        Balance = balance;
        Requested = requested;
    }
}

class Program
{
    static decimal balance = 40m;

    static void Withdraw(decimal amount)
    {
        if (amount > balance) throw new InsufficientFundsException(balance, amount);
        balance -= amount;
    }

    static void Main()
    {
        try
        {
            Withdraw(25m);
            Withdraw(25m);
        }
        catch (InsufficientFundsException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Short by " + (e.Requested - e.Balance));
        }
    }
}

المخرجات:

Cannot withdraw 25 from a balance of 15.
Short by 10

الأعراف:

• ينتهي الاسم بـ Exception.
• يشتق من Exception (أو من نوع مدمج أكثر تحديدًا حين يكون حالة خاصة منه، مثل InvalidOperationException).
• له المُنشئات القياسية الثلاثة: بلا شيء، والرسالة، والرسالة مع استثناء داخلي. أضف مُنشئاتك فوقها.
• البيانات الإضافية في خصائص للقراءة فقط تُضبط في المُنشئ. عندها يستطيع المعالج التصرف بحسب e.Requested بدل تحليل الرسالة.

التغليف باستثناء داخلي

حين يجب أن يظهر فشل منخفض المستوى كفشل أعلى مستوى، غلّفه. يُحفظ الأصلي كـ InnerException، فلا تضيع أي معلومة:

using System;

class ConfigException : Exception
{
    public ConfigException(string message, Exception inner) : base(message, inner) { }
}

class Program
{
    static int ReadPort(string text)
    {
        try
        {
            return int.Parse(text);
        }
        catch (FormatException e)
        {
            throw new ConfigException("Setting 'port' must be a number, got '" + text + "'.", e);
        }
    }

    static void Main()
    {
        try
        {
            ReadPort("80a");
        }
        catch (ConfigException e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Caused by: " + e.InnerException.GetType().Name);
        }
    }
}

المخرجات:

Setting 'port' must be a number, got '80a'.
Caused by: FormatException

يتعامل المستدعي الآن بمصطلحات الإعدادات، التي يفهمها، وتسجيل e.ToString() يطبع السلسلة كلها بما في ذلك FormatException وأثر مكدّسه. لا تغلّف إلا حين تضيف معنى؛ فتغليف كل استثناء في MyAppException عام لا يفعل سوى جعل المعالجات تحفر في InnerException.

الرمي مقابل إعادة نتيجة

الاستثناءات للإخفاقات التي لا يتوقعها المستدعي في التشغيل العادي. أما النتائج الروتينية، مثل بحث لا يجد شيئًا غالبًا أو مدخلات مستخدم غير صالحة غالبًا، فعُرف .NET لها هو نمط Try: أعد bool وسلّم القيمة عبر معامل out.

public bool TryWithdraw(decimal amount, out string error)
{
    if (amount > Balance) { error = "Insufficient funds."; return false; }
    Balance -= amount;
    error = null;
    return true;
}

أنواع كثيرة تقدّم الاثنين: ترمي int.Parse، وتعيد int.TryParse القيمة false؛ ويرمي dict[key]، وتعيد dict.TryGetValue القيمة false. رمي استثناء يكلّف أكثر بكثير من إعادة قيمة، فيجب ألا يقع على مسار يُنفَّذ آلاف المرات في الثانية. راجع ref وout لمعاملات out.

كتابة رسائل جيدة

يقرأ رسالة الاستثناء مطوّر ينظر في سجل. اجعلها تذكر ما الخطأ، وحيث يكون ذلك آمنًا القيمة المخالفة: "Quantity must be between 1 and 99, got 0." أفضل من "Invalid input.". اكتب جملًا كاملة، وأبعد الأسرار مثل كلمات المرور والرموز عن الرسائل، لأنها تنتهي في ملفات السجلات.

أخطاء شائعة

• رمي Exception نفسها. لا يستطيع المستدعون التقاطها انتقائيًا؛ استخدم نوعًا محددًا.
• تمرير الرسالة مكان اسم المعامل. يأخذ new ArgumentNullException("name") اسم المعامل؛ والرسالة تأتي ثانيًا.
• أسماء معاملات مكتوبة حرفيًا. استخدم nameof(param) كي تبقى صحيحة عند إعادة التسمية.
• استثناءات مخصصة بلا معنى إضافي. إن كان نوع مدمج يناسب فاستخدمه.
• فقدان الخطأ الأصلي عند التغليف. مرّره دائمًا كاستثناء داخلي.