yield (C# Reference)
When you use the yield keyword in a statement, you indicate that the method, operator, or get accessor in which it appears is an iterator. You use an iterator to perform a custom iteration over a collection. The following example shows the two forms of the yield statement.
yield return <expression>;
yield break;
Remarks
You use a yield return statement to return each element one at a time.
You consume an iterator method by using a foreach statement or LINQ query. Each iteration of the foreach loop calls the iterator method. When a yield return statement is reached in the iterator method, expression is returned, and the current location in code is retained. Execution is restarted from that location the next time that the iterator function is called.
You can use a yield break statement to end the iteration.
For more information about iterators, see Iterators (C# and Visual Basic).
Iterator Methods and get Accessors
The declaration of an iterator must meet the following requirements:
The return type must be IEnumerable, IEnumerable<T>, IEnumerator, or IEnumerator<T>.
An implicit conversion must exist from the type of expression in the yield return statement to the return type of the iterator.
You can't include a yield return or yield break statement in methods that have the following characteristics:
Anonymous methods. For more information, see Anonymous Methods (C# Programming Guide).
Methods that contain unsafe blocks. For more information, see unsafe (C# Reference).
Exception Handling
A yield return statement can't be located in a try-catch block. A yield return statement can be located in the try block of a try-finally statement.
A yield break statement can be located in a try block or a catch block but not a finally block.
If the foreach body (outside of the iterator method) throws an exception, a finally block in the iterator method is executed.
Technical Implementation
The following code returns an IEnumerable<string> from an iterator method and then iterates through its elements.
IEnumerable<string> elements = MyIteratorMethod();
foreach (string element in elements)
{
…
}
The call to MyIteratorMethod doesn't execute the body of the method. Instead the call returns an IEnumerable<string> into the elements variable.
On an iteration of the foreach loop, the MoveNext method is called for elements. This call executes the body of MyIteratorMethod until the next yield return statement is reached. The expression returned by the yield return statement determines not only the value of the element variable for consumption by the loop body but also the Current property of elements, which is an IEnumerable<string>.
On each subsequent iteration of the foreach loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a yield return statement. The foreach loop completes when the end of the iterator method or a yield break statement is reached.
Example
The following example has a yield return statement that's inside a for loop. Each iteration of the foreach statement body in Process creates a call to the Power iterator function. Each call to the iterator function proceeds to the next execution of the yield return statement, which occurs during the next iteration of the for loop.
The return type of the iterator method is IEnumerable, which is an iterator interface type. When the iterator method is called, it returns an enumerable object that contains the powers of a number.
//using System.Collections;
//using System.Diagnostics;
public static void Process()
{
// Display powers of 2 up to the exponent of 8:
foreach (int number in Power(2, 8))
{
Debug.Write(number.ToString() + " ");
}
// Output: 2 4 8 16 32 64 128 256
}
public static IEnumerable Power(int baseNumber, int highExponent)
{
int result = 1;
for (int counter = 1; counter <= highExponent; counter++)
{
result = result * baseNumber;
yield return result;
}
}
The following example demonstrates a get accessor that is an iterator. In the example, each yield return statement returns an instance of a user-defined class.
public static class GalaxyClass
{
public static void ShowGalaxies()
{
var theGalaxies = new Galaxies();
foreach (Galaxy theGalaxy in theGalaxies.NextGalaxy)
{
Debug.WriteLine(theGalaxy.Name + " " + theGalaxy.MegaLightYears.ToString());
}
}
public class Galaxies
{
public System.Collections.Generic.IEnumerable<Galaxy> NextGalaxy
{
get
{
yield return new Galaxy { Name = "Tadpole", MegaLightYears = 400 };
yield return new Galaxy { Name = "Pinwheel", MegaLightYears = 25 };
yield return new Galaxy { Name = "Milky Way", MegaLightYears = 0 };
yield return new Galaxy { Name = "Andromeda", MegaLightYears = 3 };
}
}
}
public class Galaxy
{
public String Name { get; set; }
public int MegaLightYears { get; set; }
}
C# Language Specification
For more information, see the C# Language Specification. The language specification is the definitive source for C# syntax and usage.