Extension Methods ב-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), גם אם המחלקה לא יכולה.
• היא רואה רק את מה שכל קוד חיצוני רואה: איברים ציבוריים (ובתוך אותו assembly גם internal). שדות פרטיים נשארים פרטיים.

המוסכמה היא לקרוא למחלקה על שם מה שהיא מרחיבה (StringExtensions, EnumerableExtensions) ולקבץ אותן ב-namespace כמו 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 בנוי על extension methods

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 מכסה את האופרטורים.

חייבים לייבא את ה-namespace

מתודת הרחבה נמצאת בטווח רק כשה-namespace של המחלקה הסטטית שלה מיובא עם 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 ל-namespace של ההרחבות (או, מ-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

לצד השני יש יתרון: מתודת הרחבה שלא רוצים בכל מקום יכולה לשבת ב-namespace שרק חלק מהקבצים מייבאים.

מתודות מופע גוברות

כשלטיפוס כבר יש מתודת מופע מתאימה, הקומפיילר משתמש בה ולא שוקל בכלל את ההרחבה. הרחבה עם אותה חתימה היא קוד מת בכל מקום שקורא לה בתחביר הנקודה:

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

ההרחבה עם הארגומנט האחד הפסידה למתודת המופע; זו עם שני הארגומנטים נבחרה כי אין מתודת מופע שמקבלת string. המשמעות היא גם שעדכון של ספרייה שמוסיף מתודת מופע בשם של ההרחבה שלכם מעביר בשקט את הקריאות שלכם לגרסה של הספרייה. בחרו שמות להרחבות שלא סביר שיתנגשו.

קריאה על 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

ל-enum אין מתודות משלו, ולכן הוא מטרה טבעית:

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()) { ... }

Extension members ב-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, ממשקים של ה-framework), כשרוצים את אותה פונקציית עזר על כל מימוש של ממשק, או כששרשרת נקראת טוב יותר מקריאות מקוננות. כשהמחלקה שלכם, הוסיפו במקום זאת מתודת מופע אמיתית: היא יכולה להשתמש במצב פרטי ומופיעה במקום שבו קוראים מחפשים אותה. והימנעו מהרחבה של object, שמכניסה את המתודה שלכם לרשימת ההשלמה של כל ערך בתוכנית.