yield (Référence C#)yield (C# Reference)

Lorsque vous utilisez le yield mot clé contextuel dans une instruction, vous indiquez que la méthode, l'opérateur ou l'accesseur get dans lequel il apparaît est un itérateur.When you use the yield contextual keyword in a statement, you indicate that the method, operator, or get accessor in which it appears is an iterator. L'utilisation de yield pour définir un itérateur rend une classe explicite supplémentaire inutile (la classe qui contient l'état d'une énumération ; pour obtenir un exemple, consultez IEnumerator<T>) lorsque vous implémentez les modèles IEnumerable et IEnumerator pour un type de collection personnalisé.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.

L'exemple suivant montre les deux formulaires de l'instruction yield.The following example shows the two forms of the yield statement.

yield return <expression>;
yield break;

RemarquesRemarks

Utilisez une instruction yield return pour retourner chaque élément un par un.You use a yield return statement to return each element one at a time.

La séquence retournée par une méthode d’itérateur peut être consommée à l’aide d’une instruction foreach ou d’une requête LINQ.The sequence returned from an iterator method can be consumed by using a foreach statement or LINQ query. Chaque itération de la boucle foreach appelle la méthode Iterator.Each iteration of the foreach loop calls the iterator method. Lorsqu'une instruction yield return est atteinte dans la méthode Iterator, expression est retourné, et l'emplacement dans le code est conservé.When a yield return statement is reached in the iterator method, expression is returned, and the current location in code is retained. L'exécution redémarrera à partir de cet emplacement la prochaine fois que la fonction d'itérateur sera appelée.Execution is restarted from that location the next time that the iterator function is called.

Utilisez une instruction yield break pour terminer l'itération.You can use a yield break statement to end the iteration.

Pour plus d’informations sur les itérateurs, consultez Itérateurs.For more information about iterators, see Iterators.

Méthodes Iterator et accesseurs getIterator methods and get accessors

La déclaration d'un itérateur doit respecter les spécifications suivantes :The declaration of an iterator must meet the following requirements:

Le type yield d'un itérateur qui retourne IEnumerable ou IEnumerator est object.The yield type of an iterator that returns IEnumerable or IEnumerator is object. Si l'itérateur retourne IEnumerable<T> ou IEnumerator<T>, il doit exister une conversion implicite du type de l'expression dans l'instruction yield return au paramètre de type générique.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 .

Vous ne pouvez pas inclure une instruction yield return ou yield break dans :You can't include a yield return or yield break statement in:

Gestion des exceptionsException handling

Il ne peut pas y avoir d'instruction yield return dans un bloc try-catch.A yield return statement can't be located in a try-catch block. Une instruction yield return peut se trouver dans le bloc try d'une instruction try-finally.A yield return statement can be located in the try block of a try-finally statement.

Une instruction yield break peut se trouver dans un bloc try ou un bloc catch mais pas dans un bloc finally.A yield break statement can be located in a try block or a catch block but not a finally block.

Si le corps foreach (en dehors de la méthode Iterator) lève une exception, un bloc finally de la méthode Iterator est exécuté.If the foreach body (outside of the iterator method) throws an exception, a finally block in the iterator method is executed.

Implémentation techniqueTechnical implementation

Le code suivant retourne IEnumerable<string> depuis une méthode Iterator, puis itère au sein de ses éléments.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)
{
   ...
}

L'appel à MyIteratorMethod n'exécute pas le corps de la méthode.The call to MyIteratorMethod doesn't execute the body of the method. À la place, l'appel retourne IEnumerable<string> dans la variable elements.Instead the call returns an IEnumerable<string> into the elements variable.

Dans une itération de la boucle foreach, la méthode MoveNext est appelée pour elements.On an iteration of the foreach loop, the MoveNext method is called for elements. Cet appel exécute le corps de MyIteratorMethod jusqu'à ce que l'instruction yield return suivante soit atteinte.This call executes the body of MyIteratorMethod until the next yield return statement is reached. L’expression retournée par l’instruction yield return détermine non seulement la valeur de la variable element pour la consommation par le corps de boucle, mais également la propriété Current de elements, qui est 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>.

À chaque itération suivante de la boucle foreach, l'exécution du corps de l'itérateur reprend à partir de l'emplacement où elle s'est interrompue, et s'arrête encore lorsqu'elle atteint une instruction yield return.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. La boucle foreach se termine lorsque à la fin de la méthode Iterator ou lorsqu'une instruction yield break est atteinte.The foreach loop completes when the end of the iterator method or a yield break statement is reached.

ExemplesExample

L'exemple suivant comprend une instruction yield return située dans une boucle for.The following example has a yield return statement that's inside a for loop. Chaque itération du corps d’instruction foreach dans la méthode Main crée un appel à la fonction d’itérateur Power.Each iteration of the foreach statement body in the Main method creates a call to the Power iterator function. Chaque appel à la fonction d'itérateur continue vers l'exécution suivante de l'instruction yield return, qui se produit pendant l'itération suivante de la boucle for.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.

Le type de retour de la méthode Iterator est IEnumerable, qui est un type interface itérateur.The return type of the iterator method is IEnumerable, which is an iterator interface type. Lorsque la méthode Iterator est appelée, elle retourne un objet énumérable contenant les puissances d'un nombre.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
}

ExemplesExample

L'exemple suivant illustre un accesseur get qui est un itérateur.The following example demonstrates a get accessor that is an iterator. Dans cet exemple, chaque instruction yield return retourne une instance d'une classe définie par l'utilisateur.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; }
    }
}

spécification du langage C#C# language specification

Pour plus d'informations, voir la spécification du langage C#.For more information, see the C# Language Specification. La spécification du langage est la source de référence pour la syntaxe C# et son utilisation.The language specification is the definitive source for C# syntax and usage.

Voir aussiSee also