Docs ejecutables de C#: IEnumerable y yield

Q: ¿Qué es IEnumerable en C#?

IEnumerable es la interfaz de todo lo que se puede recorrer con foreach. Tiene un solo método, GetEnumerator(), que devuelve un IEnumerator con MoveNext() y Current. Los arrays, las listas, los diccionarios, los conjuntos, las consultas LINQ y los métodos iteradores la implementan todos.

Q: ¿Qué diferencia hay entre IEnumerable y List en C#?

IEnumerable solo promete que puedes iterar; no tiene propiedad Count, ni indexador, ni Add, y puede calcularse de forma perezosa cada vez que haces el bucle. List es una colección concreta guardada en memoria con todo eso. Acepta IEnumerable en los parámetros cuando solo recorres, y devuelve una List o un IReadOnlyList cuando quien llama necesita indexar o contar.

Q: ¿Qué hace yield return en C#?

yield return value; dentro de un método que devuelve IEnumerable entrega un elemento a quien llama y pausa el método en ese punto. La siguiente vez que quien llama pide un elemento, el método se reanuda en la línea siguiente. El compilador reescribe el método como una máquina de estados, así que escribes un bucle y obtienes una secuencia perezosa.

Q: ¿Qué es yield break en C#?

yield break; termina la secuencia: el foreach de quien llama acaba con normalidad después de los elementos ya producidos. Es el equivalente de return en un iterador y se usa para parar antes, por ejemplo cuando se alcanza un límite o la entrada está vacía.

Todo bucle foreach y toda consulta LINQ funcionan a través de una interfaz pequeña: IEnumerable<T>. Entenderla explica por qué LINQ es perezoso, por qué algunas secuencias solo pueden leerse una vez y cómo yield return te permite escribir tus propias secuencias con un bucle normal.

Qué es IEnumerable

IEnumerable<T> tiene un solo método, GetEnumerator(). El enumerador que devuelve tiene MoveNext() (avanzar e indicar si hay un elemento) y Current (el elemento). Un foreach es una forma abreviada de manejar ese enumerador:

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();
    }
}

Salida:

red green blue 
red green blue

El enumerador empieza antes del primer elemento, así que el primer MoveNext() se coloca sobre él. Cuando MoveNext() devuelve false, la secuencia ha terminado. El bloque using libera el enumerador, algo que importa en los iteradores que tienen recursos como archivos abiertos.

IEnumerable frente a ICollection frente a List

Las interfaces de colección forman una escalera. Cada peldaño promete más:

Tipo	Añade	Uso típico
`IEnumerable<T>`	solo `foreach`	Parámetros que solo recorres; resultados de LINQ; secuencias perezosas
`IReadOnlyCollection<T>`	`Count`	Valores de retorno que quien llama no debe modificar
`ICollection<T>`	`Count`, `Add`, `Remove`, `Contains`	Código que añade a una colección de cualquier tipo
`IReadOnlyList<T>`	Acceso por índice `[i]`	Resultados de solo lectura con posiciones
`IList<T>`	Acceso por índice, `Insert`, `RemoveAt`	Código que edita por posición
`List<T>`	La clase concreta que implementa todas ellas	Almacenamiento

Un método que solo recorre su entrada debería aceptar IEnumerable<T>, para que quien llama pueda pasar un array, una lista, un conjunto o una consulta LINQ sin convertir nada. Un método que devuelve datos normalmente debería devolver algo que diga "esto ya está en memoria", como List<T> o IReadOnlyList<T>, porque un valor de retorno IEnumerable<T> podría ser una consulta que hace trabajo cada vez que se lee.

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)));
    }
}

Salida:

Escribir un iterador con yield return

Para producir tu propia secuencia, escribe un método que devuelva IEnumerable<T> y usa yield return para cada elemento. El compilador convierte el método en una clase que implementa el enumerador por ti.

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();
    }
}

Salida:

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

No hay ninguna lista en EvenNumbers. Cada yield return entrega un valor a quien llama y pausa el método, manteniendo vivas sus variables locales (i aquí) hasta que quien llama pide el siguiente valor.

Pereza: fíjate en el orden de ejecución

Como el método se pausa, su cuerpo y el bucle de quien llama se turnan. Imprimir desde los dos lados muestra cómo se intercalan:

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);
        }
    }
}

Salida:

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

Llamar a Numbers() no imprimió "start": solo creó el enumerable. El cuerpo empezó en el primer MoveNext() dentro del foreach, se ejecutó hasta el primer yield return y se detuvo. Cada paso posterior se reanudó en la línea que sigue al yield. Where y Select de LINQ se comportan igual (el runtime los implementa con clases de enumerador escritas a mano por velocidad, pero el efecto es idéntico), y por eso las consultas LINQ son diferidas.

yield break

yield break termina la secuencia antes de tiempo; es la versión de return para iteradores:

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);
        }
    }
}

Salida:

Subject: Invoice
From: shop@example.com

No puedes mezclar return value; y yield return en un mismo método. En cuanto un método contiene yield, es un iterador, y yield break es la única forma de salir antes.

Secuencias infinitas

Como solo se calculan los elementos que se piden, un iterador puede describir una secuencia sin fin. Quien la consume decide cuánto toma:

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"));
        }
    }
}

Salida:

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) es seguro aquí porque Take y First dejan de pedir cuando ya tienen lo que necesitan. En cambio, llamar a ToList() o Count() sobre una secuencia infinita nunca termina, y tampoco enumerar un OrderBy sobre ella, porque ordenar necesita antes todos los elementos.

Trampas de las secuencias perezosas

Las comprobaciones de argumentos se ejecutan tarde. Todo el cuerpo de un iterador se difiere, incluida la validación del principio. La solución es dividir el método: un método normal comprueba los argumentos y devuelve el resultado de un iterador privado.

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");
        }
    }
}

Salida:

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

Cada enumeración vuelve a ejecutar el método. Un iterador no guarda nada en caché. Recorrer dos veces Numbers() imprime "start" dos veces, vuelve a leer el archivo dos veces o llama dos veces al servicio web. Los IDE lo señalan como "possible multiple enumeration of IEnumerable". Llama una vez a ToList() cuando necesites los elementos más de una vez.

finally se ejecuta cuando el consumidor se detiene. Si quien llama sale antes del foreach, el enumerador se libera y se ejecuta cualquier bloque finally del iterador, que es como un iterador que lee un archivo lo cierra:

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");
    }
}

Salida:

open sensor
10
20
30
close sensor
done

Algunas reglas que el compilador impone a los iteradores: yield return no puede aparecer dentro de un bloque try que tenga un catch (un try/finally no da problemas), dentro de una lambda o un método anónimo, ni en un método con parámetros ref u out.

Flujos async

Para secuencias cuyos elementos llegan de forma asíncrona (páginas de una API, filas de una base de datos), C# 8 y posteriores (con .NET Core 3.0 o posterior) combinan los iteradores con await mediante 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);
}

Quien consume usa await foreach, y cada elemento se espera a medida que se produce.

Errores comunes

Devolver IEnumerable<T> desde una consulta y leerlo muchas veces. Cada lectura la vuelve a ejecutar; devuelve una List<T> en su lugar.
Validar argumentos en un iterador. La comprobación se difiere; divídelo en un método envoltorio y un iterador.
Llamar a Count() o ToList() sobre un iterador infinito. Nunca termina; usa antes Take.
Esperar que un parámetro IEnumerable<T> tenga Count o [i]. Usa el Count() de LINQ (que puede enumerar) o acepta IReadOnlyList<T>.

Preguntas frecuentes

¿Qué es IEnumerable en C#?

IEnumerable<T> es la interfaz de todo lo que se puede recorrer con foreach. Tiene un solo método, GetEnumerator(), que devuelve un IEnumerator<T> con MoveNext() y Current. Los arrays, las listas, los diccionarios, los conjuntos, las consultas LINQ y los métodos iteradores la implementan todos.

¿Qué diferencia hay entre IEnumerable y List en C#?

IEnumerable<T> solo promete que puedes iterar; no tiene propiedad Count, ni indexador, ni Add, y puede calcularse de forma perezosa cada vez que haces el bucle. List<T> es una colección concreta guardada en memoria con todo eso. Acepta IEnumerable<T> en los parámetros cuando solo recorres, y devuelve una List<T> o un IReadOnlyList<T> cuando quien llama necesita indexar o contar.

¿Qué hace yield return en C#?

yield return value; dentro de un método que devuelve IEnumerable<T> entrega un elemento a quien llama y pausa el método en ese punto. La siguiente vez que quien llama pide un elemento, el método se reanuda en la línea siguiente. El compilador reescribe el método como una máquina de estados, así que escribes un bucle y obtienes una secuencia perezosa.

¿Qué es yield break en C#?

yield break; termina la secuencia: el foreach de quien llama acaba con normalidad después de los elementos ya producidos. Es el equivalente de return en un iterador y se usa para parar antes, por ejemplo cuando se alcanza un límite o la entrada está vacía.

¿Por qué mi método iterador no lanza una excepción cuando lo llamo?

El cuerpo de un método iterador no se ejecuta hasta que se enumera la secuencia, así que las comprobaciones de argumentos del principio se ejecutan en el primer MoveNext, no en la llamada. Para validar de inmediato, pon las comprobaciones en un método público normal que después llame a un método iterador privado con las sentencias yield.

Conceptos relacionados