How do iterators work in C#? Explain yield return and yield break, what state machine the compiler generates, lazy evaluation, how try/finally and using behave inside iterators, the restrictions on iterator methods, async iterators, and the performance trade-offs of yield.

1. State machine sketch

private sealed class <ParseLines>d__0 : IEnumerable<OrderLine>, IEnumerator<OrderLine>
{
    private int <>1__state;            // -2: not started (enumerable), 0: start, 1: after yield, -1: finished
    private OrderLine <>2__current;
    private int <>l__initialThreadId;
    private TextReader reader;          // parameter copy
    private string? <line>5__1;         // hoisted local

    public bool MoveNext()
    {
        switch (<>1__state)
        {
            case 0: <>1__state = -1; goto loop;
            case 1: <>1__state = -1; goto loop;   // resume after yield
            default: return false;
        }
    loop:
        while ((<line>5__1 = reader.ReadLine()) != null)
        {
            if (<line>5__1.StartsWith("#")) continue;
            if (<line>5__1 == "END") return false;
            <>2__current = OrderLine.Parse(<line>5__1);
            <>1__state = 1;
            return true;
        }
        return false;
    }
}

With try/finally, states encode "inside try" so Dispose() knows which finally blocks to run.

2. GetEnumerator reuse

The same object implements both interfaces. If GetEnumerator() is called on the thread that created it and it hasn't started, it returns this (saving an allocation); otherwise it creates a new instance with copied parameters. That's why enumerating twice restarts the method.

3. Async iterator internals

Async iterators generate a class implementing IAsyncEnumerable<T>, IAsyncEnumerator<T>, and IValueTaskSource<bool>/IValueTaskSource, using ManualResetValueTaskSourceCore<bool> to avoid allocations per MoveNextAsync. Cancellation flows via [EnumeratorCancellation]; DisposeAsync runs finally blocks, including await using disposals.

4. Exceptions inside iterators

Exceptions thrown in the body propagate out of MoveNext() to the consumer, at enumeration time. You can't wrap yield return in try/catch, so error handling for per-item failures usually goes in a helper that returns a result (e.g. TryParse) and the iterator yields valid items or error records.

5. Iterators vs materialised collections

Try it yourself

1. Add logging inside an iterator and observe when it runs relative to the call and foreach.
2. Use using inside an iterator and break after the first item; confirm disposal.
3. Write an async iterator over a paged API with cancellation.
4. Benchmark an iterator vs returning an array for summing 100 small items.

using System.Runtime.CompilerServices;

namespace Advanced.Iterators;

public sealed record LogEntry(DateTimeOffset Timestamp, string Level, string Message);

public static class LogReader
{
    // Streams a huge file one line at a time
    public static IEnumerable<LogEntry> Read(string path)
    {
        ArgumentException.ThrowIfNullOrEmpty(path);
        return Iterator(path);

        static IEnumerable<LogEntry> Iterator(string path)
        {
            using var reader = new StreamReader(path);
            try
            {
                while (reader.ReadLine() is { } line)
                {
                    if (line.Length == 0) continue;
                    if (line == "--END--") yield break;          // stop the sequence early

                    var parts = line.Split('|', 3);
                    if (parts.Length < 3) continue;                 // skip malformed lines
                    yield return new LogEntry(DateTimeOffset.Parse(parts[0]), parts[1], parts[2]);
                }
            }
            finally
            {
                Console.WriteLine("log reader disposed");          // runs even if the consumer stops early
            }
        }
    }

    // Infinite sequence: always combine with Take/First
    public static IEnumerable<int> RetryDelaysMs()
    {
        var delay = 100;
        while (true)
        {
            yield return delay;
            delay = Math.Min(delay * 2, 10_000);
        }
    }

    // Async iterator
    public static async IAsyncEnumerable<int> PollAsync(int times, [EnumeratorCancellation] CancellationToken ct = default)
    {
        for (var i = 1; i <= times; i++)
        {
            await Task.Delay(10, ct);
            yield return i;
        }
    }
}

public static class Program
{
    public static async Task Main()
    {
        var path = Path.GetTempFileName();
        await File.WriteAllLinesAsync(path,
        [
            "2026-10-23T10:00:00+11:00|INFO|start",
            "2026-10-23T10:00:01+11:00|ERROR|payment timeout",
            "--END--",
            "2026-10-23T10:00:02+11:00|INFO|never read",
        ]);

        var firstError = LogReader.Read(path).First(e => e.Level == "ERROR"); // stops early, finally runs
        Console.WriteLine(firstError.Message);

        Console.WriteLine(string.Join(",", LogReader.RetryDelaysMs().Take(6)));  // 100,200,400,800,1600,3200

        await foreach (var n in LogReader.PollAsync(3)) Console.WriteLine($"poll {n}");
    }
}