Ardalis.SmartEnum لـ C# (.NET): دليل شامل مع أمثلة

1. ما هي ولماذا تحتاجها

Ardalis.SmartEnum هي مكتبة للغة C# (.NET) تحل واحدة من أكثر المشاكل شيوعاً في التطوير: صعوبة التعامل مع التعدادات (enum). التعدادات المدمجة في C# هي في الأساس مجموعة من الثوابت الصحيحة. لا يمكنها احتواء منطق، أو حقول إضافية (مثل وصف، رمز عملة، لون) أو دوال. هذا يؤدي إلى تضخم الكود باستخدام switch أو if-else، مما ينتهك مبادئ SOLID (خاصة مبدأ Open/Closed) ويجعل الكود أقل قابلية للصيانة.

تقدم SmartEnum بديلاً: التعدادات الذكية (Smart Enums). وهي كلاسات ترث من الكلاس الأساسي SmartEnum<TEnum, TValue>. كل قيمة من هذا التعداد هي حقل ثابت (Singleton). بفضل هذا، يمكنك إضافة أي خصائص (Name, Value إلزاميان، بالإضافة إلى أي خصائص مخصصة)، ودوال، وحتى تنفيذ واجهات (Interfaces). هذا يحول التعداد من مجرد مجموعة أرقام إلى كائن متكامل بسلوك.

لماذا تحتاجها؟ أولاً، من أجل سلامة النوع (Type Safety). لن تتمكن من تعيين قيمة غير معرفة في التعداد لمتغير (على عكس التعدادات العادية حيث يمكنك فعل (MyEnum)42). ثانياً، من أجل تغليف المنطق (Encapsulation). بدلاً من كتابة دوال مساعدة أو كلاسات أدوات، تضع المنطق مباشرة داخل التعداد. ثالثاً، من أجل قابلية القراءة. يصبح الكود موثقاً ذاتياً: كل قيمة تعداد تحمل ليس فقط اسماً، بل سياقاً كاملاً.

2. التثبيت

يتم تثبيت المكتبة عبر NuGet. قم بتنفيذ أحد الأوامر التالية في وحدة تحكم مدير الحزم أو في terminal .NET CLI:

# عبر .NET CLI
dotnet add package Ardalis.SmartEnum

# عبر Package Manager Console
Install-Package Ardalis.SmartEnum

بعد التثبيت، أضف using Ardalis.SmartEnum; في بداية الملف.

3. بداية سريعة — مثال عملي بسيط

لننشئ تعداداً بسيطاً لأيام الأسبوع. لاحظ: نحن نرث من SmartEnum<TEnum, TValue>، حيث TEnum هو الكلاس الخاص بنا، و TValue هو نوع القيمة (عادة int أو string).

using Ardalis.SmartEnum;

public sealed class Weekday : SmartEnum<Weekday, int>
{
    // الحقول الثابتة — وهي قيم التعداد
    public static readonly Weekday Monday = new Weekday(nameof(Monday), 1);
    public static readonly Weekday Tuesday = new Weekday(nameof(Tuesday), 2);
    public static readonly Weekday Wednesday = new Weekday(nameof(Wednesday), 3);
    public static readonly Weekday Thursday = new Weekday(nameof(Thursday), 4);
    public static readonly Weekday Friday = new Weekday(nameof(Friday), 5);
    public static readonly Weekday Saturday = new Weekday(nameof(Saturday), 6);
    public static readonly Weekday Sunday = new Weekday(nameof(Sunday), 7);

    // المُنشئ الخاص إلزامي
    private Weekday(string name, int value) : base(name, value) { }
}

// الاستخدام
public class Program
{
    public static void Main()
    {
        var today = Weekday.Monday;
        Console.WriteLine(today.Name);   // Monday
        Console.WriteLine(today.Value);  // 1

        // البحث حسب القيمة
        var dayFromValue = Weekday.FromValue(3);
        Console.WriteLine(dayFromValue.Name); // Wednesday

        // البحث حسب الاسم
        var dayFromName = Weekday.FromName("Friday");
        Console.WriteLine(dayFromName.Value); // 5
    }
}