迭代器可用來遍歷清單和陣列等集合。
迭代器方法或 get 存取子會在集合上執行自訂的迭代。 反覆運算器方法會使用 yield return 語句一次傳回每個元素。 當到達yield return語句時，會記住程式碼中的目前位置。 下次呼叫反覆運算器函式時，會從該位置重新啟動執行。
您可以使用 foreach 語句或使用 LINQ 查詢，從用戶端程式代碼取用反覆運算器。
在下列範例中，foreach 迴圈的第一次迭代會導致執行 SomeNumbers 迭代器方法，直到到達第一個 yield return 語句為止。 這個迭代會傳回值 3，並保留在迭代方法中的目前位置。 在下一次迴圈執行中，迭代器方法中的執行將從上次停止的位置繼續，當它到達 yield return 語句時會停止。 這次迭代會傳回值 5，而迭代器方法中的目前位置仍然保留。 當到達反覆運算器方法的結尾時，迴圈就會完成。
static void Main()
{
foreach (int number in SomeNumbers())
{
Console.Write(number.ToString() + " ");
}
// Output: 3 5 8
Console.ReadKey();
}
public static System.Collections.IEnumerable SomeNumbers()
{
yield return 3;
yield return 5;
yield return 8;
}
反覆運算器方法或 get 存取子的傳回型別可以是 IEnumerable、IEnumerable<T>、IEnumerator 或 IEnumerator<T>。
您可以使用 yield break 語句結束反覆專案。
備註
針對本主題中除了 Simple Iterator 範例以外的所有範例，請包含 using 指示詞，用於System.Collections和System.Collections.Generic命名空間。
簡單反覆運算器
下列範例具有一個單一語句，該語句位於 yield return 迴圈內。 在 Main 中，foreach 語句主體的每個迴圈都會建立對迭代器函式的呼叫，該函式會繼續到下一個 yield return 語句。
static void Main()
{
foreach (int number in EvenSequence(5, 18))
{
Console.Write(number.ToString() + " ");
}
// Output: 6 8 10 12 14 16 18
Console.ReadKey();
}
public static System.Collections.Generic.IEnumerable<int>
EvenSequence(int firstNumber, int lastNumber)
{
// Yield even numbers in the range.
for (int number = firstNumber; number <= lastNumber; number++)
{
if (number % 2 == 0)
{
yield return number;
}
}
}
建立集合類別
在下列範例中，類別DaysOfTheWeek實作了需要IEnumerable方法的GetEnumerator介面。 編譯程式會隱含呼叫 GetEnumerator 方法，這個方法會 IEnumerator傳回 。
方法 GetEnumerator 會使用 yield return 語句一次傳回每個字串。
static void Main()
{
DaysOfTheWeek days = new DaysOfTheWeek();
foreach (string day in days)
{
Console.Write(day + " ");
}
// Output: Sun Mon Tue Wed Thu Fri Sat
Console.ReadKey();
}
public class DaysOfTheWeek : IEnumerable
{
private string[] days = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
public IEnumerator GetEnumerator()
{
for (int index = 0; index < days.Length; index++)
{
// Yield each day of the week.
yield return days[index];
}
}
}
下列範例會建立包含 Zoo 動物集合的類別。
foreach參考類別實例 （theZoo） 的語句會隱含呼叫 GetEnumerator 方法。
foreach語句參考Birds和Mammals屬性，使用AnimalsForType具名反覆運算器方法。
static void Main()
{
Zoo theZoo = new Zoo();
theZoo.AddMammal("Whale");
theZoo.AddMammal("Rhinoceros");
theZoo.AddBird("Penguin");
theZoo.AddBird("Warbler");
foreach (string name in theZoo)
{
Console.Write(name + " ");
}
Console.WriteLine();
// Output: Whale Rhinoceros Penguin Warbler
foreach (string name in theZoo.Birds)
{
Console.Write(name + " ");
}
Console.WriteLine();
// Output: Penguin Warbler
foreach (string name in theZoo.Mammals)
{
Console.Write(name + " ");
}
Console.WriteLine();
// Output: Whale Rhinoceros
Console.ReadKey();
}
public class Zoo : IEnumerable
{
// Private members.
private List<Animal> animals = new List<Animal>();
// Public methods.
public void AddMammal(string name)
{
animals.Add(new Animal { Name = name, Type = Animal.TypeEnum.Mammal });
}
public void AddBird(string name)
{
animals.Add(new Animal { Name = name, Type = Animal.TypeEnum.Bird });
}
public IEnumerator GetEnumerator()
{
foreach (Animal theAnimal in animals)
{
yield return theAnimal.Name;
}
}
// Public members.
public IEnumerable Mammals
{
get { return AnimalsForType(Animal.TypeEnum.Mammal); }
}
public IEnumerable Birds
{
get { return AnimalsForType(Animal.TypeEnum.Bird); }
}
// Private methods.
private IEnumerable AnimalsForType(Animal.TypeEnum type)
{
foreach (Animal theAnimal in animals)
{
if (theAnimal.Type == type)
{
yield return theAnimal.Name;
}
}
}
// Private class.
private class Animal
{
public enum TypeEnum { Bird, Mammal }
public string Name { get; set; }
public TypeEnum Type { get; set; }
}
}
使用迭代器搭配泛型清單
在下列範例中 Stack<T> ，泛型類別會實作 IEnumerable<T> 泛型介面。 方法 Push 會將值指派給類型的 T陣列。 方法 GetEnumerator 會使用 yield return 語句傳回陣列值。
除了泛型 GetEnumerator 方法之外，也必須實作非泛型 GetEnumerator 方法。 這是因為 IEnumerable<T> 繼承自 IEnumerable。 非泛型實作會延遲至泛型實作。
此範例使用命名迭代器來支援各種遍歷相同集合數據的方法。 這些具名反覆運算器是 TopToBottom 和 BottomToTop 屬性，以及 TopN 方法。
屬性 BottomToTop 在 get 存取子中使用迭代器。
static void Main()
{
Stack<int> theStack = new Stack<int>();
// Add items to the stack.
for (int number = 0; number <= 9; number++)
{
theStack.Push(number);
}
// Retrieve items from the stack.
// foreach is allowed because theStack implements IEnumerable<int>.
foreach (int number in theStack)
{
Console.Write("{0} ", number);
}
Console.WriteLine();
// Output: 9 8 7 6 5 4 3 2 1 0
// foreach is allowed, because theStack.TopToBottom returns IEnumerable(Of Integer).
foreach (int number in theStack.TopToBottom)
{
Console.Write("{0} ", number);
}
Console.WriteLine();
// Output: 9 8 7 6 5 4 3 2 1 0
foreach (int number in theStack.BottomToTop)
{
Console.Write("{0} ", number);
}
Console.WriteLine();
// Output: 0 1 2 3 4 5 6 7 8 9
foreach (int number in theStack.TopN(7))
{
Console.Write("{0} ", number);
}
Console.WriteLine();
// Output: 9 8 7 6 5 4 3
Console.ReadKey();
}
public class Stack<T> : IEnumerable<T>
{
private T[] values = new T[100];
private int top = 0;
public void Push(T t)
{
values[top] = t;
top++;
}
public T Pop()
{
top--;
return values[top];
}
// This method implements the GetEnumerator method. It allows
// an instance of the class to be used in a foreach statement.
public IEnumerator<T> GetEnumerator()
{
for (int index = top - 1; index >= 0; index--)
{
yield return values[index];
}
}
IEnumerator IEnumerable.GetEnumerator()
{
return GetEnumerator();
}
public IEnumerable<T> TopToBottom
{
get { return this; }
}
public IEnumerable<T> BottomToTop
{
get
{
for (int index = 0; index <= top - 1; index++)
{
yield return values[index];
}
}
}
public IEnumerable<T> TopN(int itemsFromTop)
{
// Return less than itemsFromTop if necessary.
int startIndex = itemsFromTop >= top ? 0 : top - itemsFromTop;
for (int index = top - 1; index >= startIndex; index--)
{
yield return values[index];
}
}
}
語法資訊
反覆運算器可以作為方法或 get 存取子。 反覆運算器無法在事件、實例建構函式、靜態建構函式或靜態完成項中發生。
隱含轉換必須存在於語句中的 yield return 表達式類型到迭代器所傳回的型別參數 IEnumerable<T>。
在 C# 中，反覆運算器方法不能有任何 in、 ref或 out 參數。
在 C# 中，yield不是保留字，而且只有在 或 return 關鍵詞之前break使用時，才具有特殊意義。
技術實作
雖然您將反覆運算器撰寫為方法，但編譯程式會將它轉譯成巢狀類別，也就是實際上的狀態機器。 只要客戶端程式代碼中的循環繼續，這個類別就會追蹤反覆運算器 foreach 的位置。
若要查看編譯程式的功能，您可以使用 Ildasm.exe 工具來檢視針對反覆運算器方法產生的通用中繼語言程式代碼。
當您為 類別 或 結構建立反覆運算器時，不需要實作整個 IEnumerator 介面。 當編譯程式偵測到反覆運算器時，它會自動產生 Current或 MoveNext 介面的 Dispose 、 IEnumerator和 IEnumerator<T> 方法。
在每次迭代的foreach迴圈（或直接呼叫IEnumerator.MoveNext）中，下一個迭代器的程式碼主體會在前一個yield return語句之後續行執行。 然後它會繼續執行下一個 yield return 語句，一直到達迭代器主體結尾或遇到 yield break 語句為止。
反覆運算器不支援 IEnumerator.Reset 方法。 若要從頭開始重申，您必須取得新的反覆運算器。 在反覆運算器方法傳回的反覆運算器上呼叫 Reset 會 NotSupportedException擲回 。
如需詳細資訊，請參閱 C# 語言規格。
使用迭代器
當您需要使用複雜的程式代碼來填入清單序列時，迭代器可讓您在循環中保持 foreach 的簡單性。 當您想要執行下列動作時，這非常有用：
在第一次
foreach迴圈迭代次數後修改清單順序。避免在第一次迭代
foreach迴圈之前完整載入大型清單。 例如，分頁提取以載入一批表格行。 另一個範例是 EnumerateFiles 方法，它會在 .NET 中實作反覆運算器。在迭代器中封裝列表的建立。 在反覆運算器方法中，您可以建置清單，然後在迴圈中產生每個結果。
