yield (C#-Referenz)yield (C# Reference)

Wenn Sie das yield-Schlüsselwort in einer Anweisung verwenden, geben Sie damit an, dass die Methode, der Operator oder der get-Accessor, in dem es vorkommt, ein Iterator ist.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. Wird ein Iterator mithilfe von yield definiert, ist eine explizite zusätzliche Klasse (die Klasse, die den Zustand für eine Enumeration enthält, siehe beispielsweise IEnumerator<T>) nicht erforderlich, wenn Sie das IEnumerable-Muster und das IEnumerator-Muster für einen benutzerdefinierten Auflistungstyp implementieren.Using yield to define an iterator removes the need for an explicit extra class (the class that holds the state for an enumeration, see IEnumerator<T> for an example) when you implement the IEnumerable and IEnumerator pattern for a custom collection type.

Im folgenden Beispiel werden zwei Formen der yield-Anweisung gezeigt.The following example shows the two forms of the yield statement.

yield return <expression>;  
yield break;  

HinweiseRemarks

Sie verwenden eine yield return-Anweisung, um jedes Element einzeln zurückzugeben.You use a yield return statement to return each element one at a time.

Sie erzeugen eine Iteratormethode, indem Sie eine foreach-Anweisung oder eine LINQ-Abfrage verwenden.You consume an iterator method by using a foreach statement or LINQ query. Jede Iteration der foreach-Schleife ruft die Iteratormethode auf.Each iteration of the foreach loop calls the iterator method. Wenn eine yield return-Anweisung im Iterator erreicht wird, wird ein expression-Ausdruck zurückgegeben, und die aktuelle Position im Code wird beibehalten.When a yield return statement is reached in the iterator method, expression is returned, and the current location in code is retained. Wenn die Iteratorfunktion das nächste Mal aufgerufen wird, wird die Ausführung von dieser Position neu gestartet.Execution is restarted from that location the next time that the iterator function is called.

Sie verwenden eine yield break-Anweisung, um die Iteration zu beenden.You can use a yield break statement to end the iteration.

Weitere Informationen zu Iteratoren finden Sie unter Iterators (Iteratoren).For more information about iterators, see Iterators.

Iteratormethoden und Get-ZugriffsmethodenIterator Methods and get Accessors

Die Deklaration eines Iterators muss die folgenden Anforderungen erfüllen:The declaration of an iterator must meet the following requirements:

Der yield-Typ eines Iterators, der IEnumerable oder IEnumerator zurückgibt, ist object.The yield type of an iterator that returns IEnumerable or IEnumerator is object. Wenn der Iterator IEnumerable<T> oder IEnumerator<T> zurückgibt, ist eine implizite Konvertierung vom Typ des Ausdrucks in der yield return-Anweisung in den generischen Typparameter erforderlich.If the iterator returns IEnumerable<T> or IEnumerator<T>, there must be an implicit conversion from the type of the expression in the yield return statement to the generic type parameter .

Sie können keine yield return- oder yield break-Anweisung in Methoden einbeziehen, die die folgenden Eigenschaften aufweisen:You can't include a yield return or yield break statement in methods that have the following characteristics:

  • Anonyme Methoden.Anonymous methods. Weitere Informationen finden Sie unter Anonyme Methoden.For more information, see Anonymous Methods.

  • Methoden, die unsichere Blöcke enthalten.Methods that contain unsafe blocks. Weitere Informationen finden Sie unter unsafe.For more information, see unsafe.

AusnahmebehandlungException Handling

Eine yield return-Anweisung kann sich nicht in einem try-catch-Block befinden.A yield return statement can't be located in a try-catch block. Eine yield return-Anweisung kann sich im try-Block einer try-finally-Anweisung befinden.A yield return statement can be located in the try block of a try-finally statement.

Eine yield break-Anweisung kann sich in einem try- oder catch-Block befinden, nicht jedoch in einem finally-Block.A yield break statement can be located in a try block or a catch block but not a finally block.

Wenn der foreach-Text (außerhalb der Iteratormethode) eine Ausnahme auslöst, wird ein finally-Block in der Iteratormethode ausgeführt.If the foreach body (outside of the iterator method) throws an exception, a finally block in the iterator method is executed.

Technische ImplementierungTechnical Implementation

Der folgende Code gibt einen IEnumerable<string> aus einer Iteratormethode zurück und durchläuft dann die Elemente.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)  
{  
   ...  
}  

Der Aufruf von MyIteratorMethod führt nicht den Text der Methode aus.The call to MyIteratorMethod doesn't execute the body of the method. Stattdessen gibt der Aufruf einen IEnumerable<string> in die Variable elements zurück.Instead the call returns an IEnumerable<string> into the elements variable.

Bei einer Iteration der foreach-Schleife wird die Methode MoveNext für elements aufgerufen.On an iteration of the foreach loop, the MoveNext method is called for elements. Dieser Aufruf führt MyIteratorMethod aus, bis die nächste yield return-Anweisung erreicht ist.This call executes the body of MyIteratorMethod until the next yield return statement is reached. Der zurückgegebene Ausdruck der yield return -Anweisung bestimmt, nicht nur den Wert des der element -Variable für die Verwendung vom Schleifentext, sondern auch die Current Eigenschaft elements, also ein IEnumerable<string>.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>.

Bei jeder nachfolgenden Iteration der foreach-Schleife wird die Ausführung des Iteratortexts da fortgesetzt, wo sie beendet wurde, und endet dann wieder an einer yield return-Anweisung.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. Die foreach-Schleife wird beendet, wenn das Ende der Iteratormethode oder eine yield break-Anweisung erreicht wird.The foreach loop completes when the end of the iterator method or a yield break statement is reached.

BeispielExample

Das folgende Beispiel weist eine yield return-Anweisung auf, die sich innerhalb einer for-Schleife befindet.The following example has a yield return statement that's inside a for loop. Jede Iteration des foreach-Anweisungstexts in Process erzeugt einen Aufruf an die Power-Iteratorfunktion.Each iteration of the foreach statement body in Process creates a call to the Power iterator function. Jeder Aufruf der Iteratorfunktion führt bei der nächsten Iteration der yield return-Schleife zur nächsten Ausführung der for-Anweisung.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.

Der Rückgabetyp der Iteratormethode ist IEnumerable, was ein Iteratorschnittstellentyp ist.The return type of the iterator method is IEnumerable, which is an iterator interface type. Wird die Iteratormethode aufgerufen wird, gibt sie ein aufzählbares Objekt zurück, das die Potenzen einer Zahl enthält.When the iterator method is called, it returns an enumerable object that contains the powers of a number.

public class PowersOf2
{
    static void Main()
    {
        // Display powers of 2 up to the exponent of 8:
        foreach (int i in Power(2, 8))
        {
            Console.Write("{0} ", i);
        }
    }

    public static System.Collections.Generic.IEnumerable<int> Power(int number, int exponent)
    {
        int result = 1;

        for (int i = 0; i < exponent; i++)
        {
            result = result * number;
            yield return result;
        }
    }

    // Output: 2 4 8 16 32 64 128 256
}

BeispielExample

Das folgende Beispiel zeigt einen get-Accessor, der ein Iterator ist.The following example demonstrates a get accessor that is an iterator. Im Beispiel gibt jede yield return-Anweisung eine Instanz einer benutzerdefinierten Klasse zurück.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#-ProgrammiersprachenspezifikationC# Language Specification

Weitere Informationen erhalten Sie unter C#-Sprachspezifikation. Die Sprachspezifikation ist die verbindliche Quelle für die Syntax und Verwendung von C#.

Siehe auchSee Also

C#-ReferenzC# Reference
C#-ProgrammierhandbuchC# Programming Guide
foreach, inforeach, in
IteratorenIterators