دوال التوسيع في C#: الصياغة وIEnumerable وLINQ والقواعد

تضيف دالة التوسيع (extension method) دالة إلى نوع موجود دون تعديله أو الوراثة منه أو تغليفه. تكتب دالة ساكنة عادية، وتعلّم معاملها الأول بـ this، ويستخدمها المستدعون بصياغة النقطة كأن النوع كان يملكها دائمًا:

using System;

static class StringExtensions
{
    public static string Truncate(this string text, int maxLength)
    {
        if (text.Length <= maxLength) return text;
        return text.Substring(0, maxLength) + "...";
    }

    public static int WordCount(this string text) =>
        text.Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries).Length;
}

class Program
{
    static void Main()
    {
        string title = "Extension methods let you add behavior to types you do not own";

        Console.WriteLine(title.Truncate(24));
        Console.WriteLine(title.WordCount());
        Console.WriteLine("short".Truncate(24));

        Console.WriteLine(StringExtensions.Truncate(title, 9));   // the same method, called directly
    }
}

المخرجات:

Extension methods let yo...
12
short
Extension...

تُترجم title.Truncate(24) إلى StringExtensions.Truncate(title, 24) بالضبط. صياغة النقطة مجرد تسهيل: ما زالت الدالة ساكنة، وما زالت تعيش في StringExtensions، ولا تستطيع استخدام إلا الأعضاء العامة في string.

قواعد التصريح بها

• يجب أن تكون الدالة static وأن تعيش في صنف static وغير عام وغير متداخل داخل صنف آخر. الصنف غير الساكن أو العام يعطي CS1106، Extension method must be defined in a non-generic static class؛ والمتداخل يعطي CS1109، Extension methods must be defined in a top level static class.
• توضع this على المعامل الأول فقط، ونوع ذلك المعامل هو النوع الذي يُوسَّع. والمعاملات الأخرى عادية.
• يمكن للدالة نفسها أن تكون عامة (this IEnumerable<T> source)، مع أن الصنف لا يمكنه ذلك.
• لا ترى إلا ما تراه أي شيفرة خارجية: الأعضاء العامة (وداخل التجميع نفسه، الداخلية internal). وتبقى الحقول الخاصة خاصة.

العُرف أن يُسمّى الصنف بما يوسّعه (StringExtensions وEnumerableExtensions) وأن تُجمع في فضاء أسماء مثل MyApp.Extensions.

توسيع الواجهات وIEnumerable<T>

توسيع واجهة يضيف الدالة إلى كل نوع ينفّذها. لذا يمنح توسيع IEnumerable<T> الدالة للمصفوفات والقوائم والمجموعات ومجموعات مفاتيح القواميس ونتائج استعلامات LINQ دفعة واحدة:

using System;
using System.Collections.Generic;
using System.Linq;

static class EnumerableExtensions
{
    public static decimal Median(this IEnumerable<decimal> source)
    {
        var sorted = source.OrderBy(x => x).ToList();
        if (sorted.Count == 0) throw new InvalidOperationException("sequence is empty");
        int mid = sorted.Count / 2;
        return sorted.Count % 2 == 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
    }

    public static IEnumerable<T> EveryNth<T>(this IEnumerable<T> source, int n)
    {
        int i = 0;
        foreach (T item in source)
        {
            if (i % n == 0) yield return item;
            i++;
        }
    }
}

class Program
{
    static void Main()
    {
        decimal[] prices = { 12m, 3m, 45m, 7m };
        var orderTotals = new List<decimal> { 20m, 80m, 50m };

        Console.WriteLine(prices.Median());
        Console.WriteLine(orderTotals.Median());
        Console.WriteLine(orderTotals.Where(t => t > 25m).Median());

        string[] frames = { "f0", "f1", "f2", "f3", "f4", "f5", "f6" };
        Console.WriteLine(string.Join(" ", frames.EveryNth(3)));
    }
}

المخرجات:

9.5
50
65
f0 f3 f6

EveryNth عامة: يُستنتج T من المستقبِل، فتعمل مع النصوص هنا ومع أي نوع عناصر آخر. ولأنها تستخدم yield return فهي كسولة مثل معاملات LINQ المدمجة ويمكن سلسلتها معها.

LINQ مبني على دوال التوسيع

Where وSelect وOrderBy وSum وFirst وبقية LINQ دوال توسيع على IEnumerable<T>، معرّفة في الصنف الساكن System.Linq.Enumerable. لهذا يجب أن تكون using System.Linq; في أعلى الملف قبل أن تُترجم list.Where(...)، ولهذا يعمل LINQ على كل نوع مجموعة دون أن ينفّذ أي منها دالة Where:

using System;
using System.Linq;

class Program
{
    static void Main()
    {
        int[] scores = { 72, 95, 58, 88 };

        var passed1 = scores.Where(s => s >= 60).OrderBy(s => s);
        var passed2 = Enumerable.OrderBy(Enumerable.Where(scores, s => s >= 60), s => s);

        Console.WriteLine(string.Join(", ", passed1));
        Console.WriteLine(string.Join(", ", passed2));
    }
}

المخرجات:

72, 88, 95
72, 88, 95

السطران الشيفرة نفسها. تحوّل صياغة التوسيع الاستدعاءات المتداخلة التي تُقرأ من الداخل إلى الخارج إلى سلسلة تُقرأ بترتيب حدوث الخطوات، وهذا السبب الرئيسي لوجود دوال التوسيع: أُضيفت في C# 3 مع LINQ. تغطي صفحة LINQ المعاملات.

يجب استيراد فضاء الأسماء

لا تكون دالة التوسيع في النطاق إلا حين يُستورد فضاء أسماء صنفها الساكن بـ using. ودونها يفشل الاستدعاء كأن الدالة غير موجودة:

error CS1061: 'string' does not contain a definition for 'Truncate' and no accessible extension method 'Truncate' accepting a first argument of type 'string' could be found (are you missing a using directive or an assembly reference?)

أضف using لفضاء أسماء التوسيعات (أو، منذ C# 10، global using مرة واحدة للمشروع):

using System;
using Shop.Extensions;

namespace Shop.Extensions
{
    public static class PriceExtensions
    {
        public static string ToPriceTag(this decimal amount) => $"EUR {amount:F2}";
    }
}

class Program
{
    static void Main()
    {
        decimal total = 49.9m;
        Console.WriteLine(total.ToPriceTag());
    }
}

المخرجات:

EUR 49.90

والوجه الآخر مفيد: دالة التوسيع التي لا تريدها في كل مكان يمكن أن تعيش في فضاء أسماء لا تستورده إلا بعض الملفات.

دوال المثيل تفوز

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

using System;

class Invoice
{
    public decimal Amount = 120m;
    public string Describe() => $"Invoice (instance method): {Amount}";
}

static class InvoiceExtensions
{
    public static string Describe(this Invoice invoice) => "extension: only reachable as a static call";
    public static string Describe(this Invoice invoice, string currency) =>
        $"Invoice (extension): {invoice.Amount} {currency}";
}

class Program
{
    static void Main()
    {
        var invoice = new Invoice();
        Console.WriteLine(invoice.Describe());
        Console.WriteLine(invoice.Describe("USD"));
        Console.WriteLine(InvoiceExtensions.Describe(invoice));
    }
}

المخرجات:

Invoice (instance method): 120
Invoice (extension): 120 USD
extension: only reachable as a static call

خسر التوسيع ذو الوسيط الواحد أمام دالة المثيل؛ واستُخدم ذو الوسيطين لأنه لا توجد دالة مثيل تأخذ نصًا. وهذا يعني أيضًا أن تحديث مكتبة يضيف دالة مثيل باسم توسيعك يحوّل استدعاءاتك بصمت إلى نسخة المكتبة. اختر أسماء توسيعات يُستبعد أن تتصادم.

الاستدعاء على null

لأن الاستدعاء في الحقيقة استدعاء ساكن، لا يرمي المستقبِل null استثناءً في موضع الاستدعاء. تتلقى الدالة null كوسيطها الأول وتقرّر ما يعنيه:

using System;

static class TextExtensions
{
    public static bool IsBlank(this string s) => string.IsNullOrWhiteSpace(s);

    public static string Initials(this string fullName)
    {
        if (fullName == null) throw new ArgumentNullException(nameof(fullName));
        string result = "";
        foreach (string part in fullName.Split(' '))
            if (part.Length > 0) result += char.ToUpper(part[0]);
        return result;
    }
}

class Program
{
    static void Main()
    {
        string missing = null;

        Console.WriteLine(missing.IsBlank());
        Console.WriteLine("ada lovelace".Initials());

        try
        {
            missing.Initials();
        }
        catch (ArgumentNullException e)
        {
            Console.WriteLine($"{e.GetType().Name}: {e.ParamName}");
        }
    }
}

المخرجات:

True
AL
ArgumentNullException: fullName

إعادة missing.IsBlank() القيمة true مريحة، لكنها قد تفاجئ القرّاء الذين يتوقعون أن يرمي استدعاء عضو على null استثناءً. اقبل null فقط في الدوال التي يجعل اسمها ذلك بديهيًا (IsBlank وOrEmpty)؛ وفي غيرها ارمِ ArgumentNullException كما يفعل LINQ.

توسيع التعدادات

لا يمكن للتعدادات أن تملك دوالًا خاصة بها، وهذا يجعلها هدفًا طبيعيًا:

enum OrderStatus { Pending, Paid, Shipped, Delivered, Cancelled }

static class OrderStatusExtensions
{
    public static bool IsFinal(this OrderStatus s) =>
        s == OrderStatus.Delivered || s == OrderStatus.Cancelled;
}

// usage: if (order.Status.IsFinal()) { ... }

أعضاء التوسيع في C# 14

حتى C# 14 لم يكن يمكن أن تكون إلا الدوال توسيعات. أضافت C# 14 كتل extension، التي تجمع أعضاء لمستقبِل واحد وتسمح بخصائص التوسيع والأعضاء الساكنة أيضًا:

// C# 14 and later
public static class StringExtensions
{
    extension(string s)
    {
        public bool IsBlank => string.IsNullOrWhiteSpace(s);   // extension property
        public string Truncate(int max) => s.Length <= max ? s : s[..max] + "...";
    }
}

تبقى دوال التوسيع التقليدية بمعامل this صالحة، وهي ما تستخدمه تقريبًا كل الشيفرات والمكتبات الموجودة.

متى تكتب واحدة

تناسب دوال التوسيع حين لا تملك النوع (string وDateTime وواجهات الإطار)، وحين تريد الدالة المساعدة نفسها على كل تنفيذ لواجهة، أو حين تُقرأ السلسلة أفضل من الاستدعاءات المتداخلة. وحين تملك الصنف أضف دالة مثيل حقيقية بدلًا من ذلك: يمكنها استخدام الحالة الخاصة وتظهر حيث يبحث عنها القرّاء. وتجنّب توسيع object، الذي يضع دالتك في قائمة الإكمال لكل قيمة في البرنامج.