وثائق C# قابلة للتشغيل: IEnumerable وyield

Q: ما هي IEnumerable في C#؟

IEnumerable واجهة كل ما يمكن المرور عليه بـ foreach. لها دالة واحدة، GetEnumerator()، تعيد IEnumerator فيه MoveNext() وCurrent. تنفّذها المصفوفات والقوائم والقواميس والمجموعات واستعلامات LINQ ودوال المكرِّر كلها.

Q: ما الفرق بين IEnumerable وList في C#؟

لا تعد IEnumerable إلا بأنك تستطيع المرور؛ ليس فيها خاصية Count ولا مفهرس ولا Add، وقد تُحسب بكسل في كل مرة تمرّ فيها. أما List فمجموعة فعلية مخزّنة في الذاكرة بكل ذلك. اقبل IEnumerable في المعاملات حين تمرّ فقط، وأعد List أو IReadOnlyList حين يحتاج المستدعون إلى الفهرسة أو العدّ.

Q: ماذا تفعل yield return في C#؟

تسلّم yield return value; داخل دالة تعيد IEnumerable عنصرًا واحدًا إلى المستدعي وتوقف الدالة عند تلك النقطة. وفي المرة التالية التي يطلب فيها المستدعي عنصرًا تستأنف الدالة من السطر التالي. يعيد المترجم كتابة الدالة كآلة حالات، فتكتب حلقة وتحصل على تسلسل كسول.

Q: ما هي yield break في C#؟

تنهي yield break; التسلسل: تنتهي foreach لدى المستدعي بشكل طبيعي بعد العناصر المنتجة أصلًا. هي مكافئ return في المكرِّر وتُستخدم للتوقف مبكرًا، مثلًا حين يُبلغ حد أو تكون المدخلات فارغة.

كل حلقة foreach وكل استعلام LINQ يعمل عبر واجهة صغيرة واحدة: IEnumerable<T>. فهمها يشرح لماذا LINQ كسول، ولماذا لا يمكن قراءة بعض التسلسلات إلا مرة واحدة، وكيف تتيح لك yield return كتابة تسلسلاتك الخاصة بحلقة عادية.

ما هي IEnumerable

لـ IEnumerable<T> دالة واحدة، GetEnumerator(). وللمعدِّد الذي تعيده MoveNext() (يتقدّم، ويبلّغ هل يوجد عنصر) وCurrent (العنصر). وforeach اختصار لقيادة ذلك المعدِّد:

using System;
using System.Collections.Generic;

class Program
{
    static void Main()
    {
        IEnumerable<string> colors = new List<string> { "red", "green", "blue" };

        foreach (string c in colors)
        {
            Console.Write(c + " ");
        }
        Console.WriteLine();

        // What the foreach above compiles to, roughly:
        using (IEnumerator<string> e = colors.GetEnumerator())
        {
            while (e.MoveNext())
            {
                Console.Write(e.Current + " ");
            }
        }
        Console.WriteLine();
    }
}

المخرجات:

red green blue 
red green blue

يبدأ المعدِّد قبل العنصر الأول، فتنقله MoveNext() الأولى إليه. وحين تعيد MoveNext() القيمة false ينتهي التسلسل. وتتخلّص كتلة using من المعدِّد، وهذا مهم للمكرِّرات التي تمسك موارد مثل الملفات المفتوحة.

IEnumerable مقابل ICollection مقابل List

تشكّل واجهات المجموعات سلّمًا. كل درجة تعد بأكثر:

النوع	ما يضيفه	الاستخدام النموذجي
`IEnumerable<T>`	`foreach` فقط	معاملات تمرّ عليها فقط؛ نتائج LINQ؛ تسلسلات كسولة
`IReadOnlyCollection<T>`	`Count`	قيم معادة يجب ألا يعدّلها المستدعي
`ICollection<T>`	`Count` و`Add` و`Remove` و`Contains`	شيفرة تضيف إلى مجموعة من أي نوع
`IReadOnlyList<T>`	الوصول بالفهرس `[i]`	نتائج للقراءة فقط لها مواضع
`IList<T>`	الوصول بالفهرس و`Insert` و`RemoveAt`	شيفرة تعدّل بالموضع
`List<T>`	الصنف الفعلي الذي ينفّذ كل هذا	التخزين

الدالة التي لا تفعل سوى المرور على مدخلاتها يجب أن تقبل IEnumerable<T>، كي يستطيع المستدعون تمرير مصفوفة أو قائمة أو مجموعة أو استعلام LINQ دون تحويل. أما الدالة التي تعيد بيانات فيجب عادة أن تعيد شيئًا يقول "هذا موجود في الذاكرة أصلًا"، مثل List<T> أو IReadOnlyList<T>، لأن القيمة المعادة من نوع IEnumerable<T> قد تكون استعلامًا يؤدي عملًا في كل مرة يُقرأ فيها.

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

class Program
{
    static decimal Total(IEnumerable<decimal> amounts)
    {
        decimal sum = 0;
        foreach (decimal a in amounts) sum += a;
        return sum;
    }

    static void Main()
    {
        decimal[] array = { 10m, 20m };
        var list = new List<decimal> { 5m, 5m, 5m };
        var set = new HashSet<decimal> { 1.5m, 2.5m };

        Console.WriteLine(Total(array));
        Console.WriteLine(Total(list));
        Console.WriteLine(Total(set));
        Console.WriteLine(Total(list.Where(x => x > 1m).Select(x => x * 2)));
    }
}

المخرجات:

كتابة مكرِّر بـ yield return

لإنتاج تسلسلك الخاص اكتب دالة تعيد IEnumerable<T> واستخدم yield return لكل عنصر. يحوّل المترجم الدالة إلى صنف ينفّذ المعدِّد عنك.

using System;
using System.Collections.Generic;

class Program
{
    static IEnumerable<int> EvenNumbers(int max)
    {
        for (int i = 0; i <= max; i += 2)
        {
            yield return i;
        }
    }

    static IEnumerable<string> Weekdays()
    {
        yield return "Mon";
        yield return "Tue";
        yield return "Wed";
        yield return "Thu";
        yield return "Fri";
    }

    static void Main()
    {
        Console.WriteLine(string.Join(", ", EvenNumbers(10)));
        foreach (string d in Weekdays())
        {
            Console.Write(d + " ");
        }
        Console.WriteLine();
    }
}

المخرجات:

0, 2, 4, 6, 8, 10
Mon Tue Wed Thu Fri

لا توجد قائمة في أي مكان في EvenNumbers. تسلّم كل yield return قيمة واحدة إلى المستدعي وتوقف الدالة، مبقية متغيّراتها المحلية (i هنا) حية حتى يطلب المستدعي القيمة التالية.

الكسل: راقب ترتيب التنفيذ

لأن الدالة تتوقف، يتناوب جسمها وحلقة المستدعي. الطباعة من الطرفين تُظهر التداخل:

using System;
using System.Collections.Generic;

class Program
{
    static IEnumerable<int> Numbers()
    {
        Console.WriteLine("  start");
        for (int i = 1; i <= 3; i++)
        {
            Console.WriteLine("  yielding " + i);
            yield return i;
            Console.WriteLine("  resumed after " + i);
        }
        Console.WriteLine("  end");
    }

    static void Main()
    {
        IEnumerable<int> seq = Numbers();
        Console.WriteLine("Called Numbers(), nothing printed yet");

        foreach (int n in seq)
        {
            Console.WriteLine("Loop got " + n);
        }
    }
}

المخرجات:

Called Numbers(), nothing printed yet
  start
  yielding 1
Loop got 1
  resumed after 1
  yielding 2
Loop got 2
  resumed after 2
  yielding 3
Loop got 3
  resumed after 3
  end

لم يطبع استدعاء Numbers() كلمة "start": أنشأ القابل للتعداد فقط. بدأ الجسم عند أول MoveNext() داخل foreach، وعمل حتى أول yield return، ثم توقف. وكل خطوة لاحقة استأنفت من السطر الذي يلي yield. تتصرف Where وSelect في LINQ بالطريقة نفسها (ينفّذها وقت التشغيل بأصناف معدِّدات مكتوبة يدويًا للسرعة، لكن الأثر متطابق)، ولهذا استعلامات LINQ مؤجّلة.

yield break

تنهي yield break التسلسل مبكرًا، وهي نسخة المكرِّر من return:

using System;
using System.Collections.Generic;

class Program
{
    static IEnumerable<string> ReadUntilBlank(string[] lines)
    {
        foreach (string line in lines)
        {
            if (line.Trim().Length == 0)
            {
                yield break; // stop at the first blank line
            }
            yield return line.Trim();
        }
    }

    static void Main()
    {
        string[] input = { "Subject: Invoice", " From: shop@example.com", "", "Body text" };
        foreach (string header in ReadUntilBlank(input))
        {
            Console.WriteLine(header);
        }
    }
}

المخرجات:

Subject: Invoice
From: shop@example.com

لا يمكنك الخلط بين return value; وyield return في دالة واحدة. بمجرد أن تحتوي الدالة على yield تصبح مكرِّرًا، وyield break هي الطريقة الوحيدة لمغادرتها مبكرًا.

التسلسلات اللانهائية

لأنه لا يُحسب أبدًا إلا العناصر المطلوبة، يمكن للمكرِّر أن يصف تسلسلًا بلا نهاية. والمستهلك يقرّر كم يأخذ:

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

class Program
{
    static IEnumerable<long> Fibonacci()
    {
        long a = 0, b = 1;
        while (true)
        {
            yield return a;
            long next = a + b;
            a = b;
            b = next;
        }
    }

    static IEnumerable<DateTime> Mondays(DateTime from)
    {
        DateTime d = from;
        while (d.DayOfWeek != DayOfWeek.Monday) d = d.AddDays(1);
        while (true)
        {
            yield return d;
            d = d.AddDays(7);
        }
    }

    static void Main()
    {
        Console.WriteLine(string.Join(", ", Fibonacci().Take(10)));
        Console.WriteLine(Fibonacci().First(f => f > 1000));

        foreach (DateTime m in Mondays(new DateTime(2026, 9, 24)).Take(3))
        {
            Console.WriteLine(m.ToString("yyyy-MM-dd ddd"));
        }
    }
}

المخرجات:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34
1597
2026-09-28 Mon
2026-10-05 Mon
2026-10-12 Mon

while (true) آمنة هنا لأن Take وFirst تتوقفان عن الطلب بعد أن تحصلا على ما تحتاجانه. أما استدعاء ToList() أو Count() على تسلسل لانهائي فلا يعود أبدًا، وكذلك تعداد OrderBy عليه، لأن الفرز يحتاج إلى كل عنصر أولًا.

أفخاخ التسلسلات الكسولة

فحوص الوسائط تعمل متأخرة. جسم المكرِّر كله مؤجّل، بما في ذلك التحقق في أعلاه. الإصلاح تقسيم الدالة: دالة عادية تفحص الوسائط وتعيد نتيجة مكرِّر خاص.

using System;
using System.Collections.Generic;

class Program
{
    static IEnumerable<int> LazyRange(int count)
    {
        if (count < 0) throw new ArgumentOutOfRangeException("count");
        for (int i = 0; i < count; i++) yield return i;
    }

    static IEnumerable<int> EagerRange(int count)
    {
        if (count < 0) throw new ArgumentOutOfRangeException("count"); // runs now
        return RangeIterator(count);
    }

    static IEnumerable<int> RangeIterator(int count)
    {
        for (int i = 0; i < count; i++) yield return i;
    }

    static void Main()
    {
        IEnumerable<int> a = LazyRange(-1);
        Console.WriteLine("LazyRange(-1) returned without an error");
        try
        {
            foreach (int x in a) { }
        }
        catch (ArgumentOutOfRangeException)
        {
            Console.WriteLine("...and threw only when enumerated");
        }

        try
        {
            EagerRange(-1);
        }
        catch (ArgumentOutOfRangeException)
        {
            Console.WriteLine("EagerRange(-1) threw at the call");
        }
    }
}

المخرجات:

LazyRange(-1) returned without an error
...and threw only when enumerated
EagerRange(-1) threw at the call

كل تعداد يشغّل الدالة مجددًا. المكرِّر لا يخزّن شيئًا مؤقتًا. المرور مرتين على Numbers() يطبع "start" مرتين، أو يعيد قراءة الملف مرتين، أو يستدعي خدمة الويب مرتين. تنبّه بيئات التطوير إلى ذلك بعبارة "possible multiple enumeration of IEnumerable". استدعِ ToList() مرة واحدة حين تحتاج إلى العناصر أكثر من مرة.

تعمل finally حين يتوقف المستهلك. إن خرج المستدعي من foreach مبكرًا يُتخلّص من المعدِّد وتُنفَّذ أي كتلة finally في المكرِّر، وبهذا يغلق المكرِّر الذي يقرأ ملفًا الملف:

using System;
using System.Collections.Generic;

class Program
{
    static IEnumerable<int> Readings()
    {
        Console.WriteLine("open sensor");
        try
        {
            for (int i = 1; i <= 100; i++) yield return i * 10;
        }
        finally
        {
            Console.WriteLine("close sensor");
        }
    }

    static void Main()
    {
        foreach (int r in Readings())
        {
            Console.WriteLine(r);
            if (r >= 30) break;
        }
        Console.WriteLine("done");
    }
}

المخرجات:

open sensor
10
20
30
close sensor
done

قواعد قليلة يفرضها المترجم على المكرِّرات: لا يمكن أن تظهر yield return داخل كتلة try لها catch (أما try/finally فمقبولة)، ولا داخل تعبير lambda أو دالة مجهولة، ولا في دالة لها معاملات ref أو out.

التدفقات غير المتزامنة

للتسلسلات التي تصل عناصرها بشكل غير متزامن (صفحات من API، صفوف من قاعدة بيانات)، تجمع C# 8 وما بعدها (مع .NET Core 3.0 أو أحدث) المكرِّرات مع await عبر IAsyncEnumerable<T>:

static async IAsyncEnumerable<string> FetchPages()
{
    for (int page = 1; page <= 3; page++)
    {
        await Task.Delay(100);           // simulate a network call
        yield return $"page {page}";
    }
}

await foreach (string p in FetchPages())
{
    Console.WriteLine(p);
}

يستخدم المستهلك await foreach، ويُنتظر كل عنصر حين يُنتج.

أخطاء شائعة

إعادة IEnumerable<T> من استعلام وقراءتها مرات كثيرة. كل قراءة تعيد تشغيله؛ أعد List<T> بدلًا من ذلك.
التحقق من الوسائط داخل مكرِّر. الفحص مؤجّل؛ قسّم إلى دالة مغلّفة ومكرِّر.
استدعاء Count() أو ToList() على مكرِّر لانهائي. لا ينتهي أبدًا؛ استخدم Take أولًا.
توقّع أن يملك معامل IEnumerable<T> خاصية Count أو [i]. استخدم Count() في LINQ (التي قد تعدّد) أو اقبل IReadOnlyList<T>.

الأسئلة الشائعة

ما هي IEnumerable في C#؟

IEnumerable<T> واجهة كل ما يمكن المرور عليه بـ foreach. لها دالة واحدة، GetEnumerator()، تعيد IEnumerator<T> فيه MoveNext() وCurrent. تنفّذها المصفوفات والقوائم والقواميس والمجموعات واستعلامات LINQ ودوال المكرِّر كلها.

ما الفرق بين IEnumerable وList في C#؟

لا تعد IEnumerable<T> إلا بأنك تستطيع المرور؛ ليس فيها خاصية Count ولا مفهرس ولا Add، وقد تُحسب بكسل في كل مرة تمرّ فيها. أما List<T> فمجموعة فعلية مخزّنة في الذاكرة بكل ذلك. اقبل IEnumerable<T> في المعاملات حين تمرّ فقط، وأعد List<T> أو IReadOnlyList<T> حين يحتاج المستدعون إلى الفهرسة أو العدّ.

ماذا تفعل yield return في C#؟

تسلّم yield return value; داخل دالة تعيد IEnumerable<T> عنصرًا واحدًا إلى المستدعي وتوقف الدالة عند تلك النقطة. وفي المرة التالية التي يطلب فيها المستدعي عنصرًا تستأنف الدالة من السطر التالي. يعيد المترجم كتابة الدالة كآلة حالات، فتكتب حلقة وتحصل على تسلسل كسول.

ما هي yield break في C#؟

تنهي yield break; التسلسل: تنتهي foreach لدى المستدعي بشكل طبيعي بعد العناصر المنتجة أصلًا. هي مكافئ return في المكرِّر وتُستخدم للتوقف مبكرًا، مثلًا حين يُبلغ حد أو تكون المدخلات فارغة.

لماذا لا ترمي دالة المكرِّر عندي استثناءً حين أستدعيها؟

جسم دالة المكرِّر لا يُنفَّذ حتى يُعدَّد التسلسل، فتُنفَّذ فحوص الوسائط في أعلاه عند أول MoveNext، لا عند الاستدعاء. للتحقق الفوري ضع الفحوص في دالة عامة عادية تستدعي بعدها دالة مكرِّر خاصة تحمل عبارات yield.

مفاهيم ذات صلة