yield, instruction (Visual Basic)Yield Statement (Visual Basic)

Envoie l’élément suivant d’un regroupement à un For Each...Next instruction.Sends the next element of a collection to a For Each...Next statement.

SyntaxeSyntax

Yield expression  

ParamètresParameters

TermeTerm DéfinitionDefinition
expression Obligatoire.Required. Une expression qui est implicitement convertible au type de la fonction d’itérateur ou Get accesseur qui contienne la Yield instruction.An expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.

NotesRemarks

La Yield instruction retourne un élément d’une collection à la fois.The Yield statement returns one element of a collection at a time. Le Yield instruction est incluse dans une fonction d’itérateur ou Get accesseur, qui effectuent des itérations personnalisées sur une collection.The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

Vous consommez une fonction d’itérateur en utilisant un For Each... L’instruction suivante ou une requête LINQ.You consume an iterator function by using a For Each...Next Statement or a LINQ query. Chaque itération de la For Each boucle appelle la fonction d’itérateur.Each iteration of the For Each loop calls the iterator function. Lorsqu’un Yield instruction est atteint dans la fonction d’itérateur, expression est renvoyé, et l’emplacement actuel dans le code est conservé.When a Yield statement is reached in the iterator function, 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.

Une conversion implicite doit exister entre le type de expression dans la Yield instruction pour le type de retour de l’itérateur.An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

Vous pouvez utiliser un Exit Function ou Return instruction à la fin de l’itération.You can use an Exit Function or Return statement to end the iteration.

« Produit » n’est pas un mot réservé et a une signification spéciale uniquement lorsqu’il est utilisé dans une Iterator fonction ou Get accesseur."Yield" is not a reserved word and has special meaning only when it is used in an Iterator function or Get accessor.

Pour plus d’informations sur les fonctions d’itérateur et Get accesseurs, consultez itérateurs.For more information about iterator functions and Get accessors, see Iterators.

Fonctions d’itérateur et accesseurs GetIterator Functions and Get Accessors

La déclaration d’une fonction d’itérateur ou Get accesseur doit remplir les conditions suivantes :The declaration of an iterator function or Get accessor must meet the following requirements:

Une fonction d’itérateur ne peut pas se produire dans un événement, un constructeur d’instance, un constructeur statique ou un destructeur statique.An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.

Une fonction d’itérateur peut être une fonction anonyme.An iterator function can be an anonymous function. Pour plus d'informations, consultez Itérateurs.For more information, see Iterators.

Gestion des exceptionsException Handling

A Yield instruction peut être à l’intérieur d’un Try bloc d’un essayez... Catch... Instruction finally.A Yield statement can be inside a Try block of a Try...Catch...Finally Statement. A Try bloc qui a un Yield instruction peut avoir Catch bloque et peut avoir un Finally bloc.A Try block that has a Yield statement can have Catch blocks, and can have a Finally block.

A Yield instruction ne peut pas être à l’intérieur d’un Catch bloc ou une Finally bloc.A Yield statement cannot be inside a Catch block or a Finally block.

Si le For Each corps (en dehors de la fonction d’itérateur) lève une exception, une Catch bloc dans la fonction d’itérateur n’est pas exécutée, mais un Finally bloc dans la fonction d’itérateur est exécuté.If the For Each body (outside of the iterator function) throws an exception, a Catch block in the iterator function is not executed, but a Finally block in the iterator function is executed. A Catch bloc à l’intérieur d’une fonction d’itérateur intercepte uniquement les exceptions qui se produisent à l’intérieur de la fonction d’itérateur.A Catch block inside an iterator function catches only exceptions that occur inside the iterator function.

Implémentation techniqueTechnical Implementation

Le code suivant retourne un IEnumerable (Of String) à partir d’une fonction d’itérateur parcourt ensuite les éléments de la IEnumerable (Of String).The following code returns an IEnumerable (Of String) from an iterator function and then iterates through the elements of the IEnumerable (Of String).

Dim elements As IEnumerable(Of String) = MyIteratorFunction()  
    …  
For Each element As String In elements  
Next  

L’appel à MyIteratorFunction n’exécute pas le corps de la fonction.The call to MyIteratorFunction doesn't execute the body of the function. À la place, l'appel retourne IEnumerable(Of String) dans la variable elements.Instead the call returns an IEnumerable(Of String) into the elements variable.

Dans une itération de la boucle For Each, la méthode MoveNext est appelée pour elements.On an iteration of the For Each loop, the MoveNext method is called for elements. Cet appel exécute le corps de MyIteratorFunction jusqu'à ce que l'instruction Yield suivante soit atteinte.This call executes the body of MyIteratorFunction until the next Yield statement is reached. Le Yield instruction retourne une expression qui détermine non seulement la valeur de la element variable pour la consommation par le corps de la boucle, mais également le Current propriété d’éléments, qui est un IEnumerable (Of String).The Yield statement returns an expression that 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 (Of String).

À chaque itération suivante de la boucle For Each, 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.On each subsequent iteration of the For Each loop, the execution of the iterator body continues from where it left off, again stopping when it reaches a Yield statement. Le For Each boucle termine lorsque la fin de la fonction d’itérateur ou une Return ou Exit Function instruction est atteinte.The For Each loop completes when the end of the iterator function or a Return or Exit Function statement is reached.

ExempleExample

L’exemple suivant comprend une Yield instruction qui se trouve dans un pour... Suivant boucle.The following example has a Yield statement that is inside a For…Next loop. Chaque itération de la pour chaque corps de l’instruction dans Main crée un appel à la Power fonction d’itérateur.Each iteration of the For Each statement body in Main 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, qui se produit pendant l'itération suivante de la boucle For…Next.Each call to the iterator function proceeds to the next execution of the Yield statement, which occurs during the next iteration of the For…Next loop.

Le type de retour de la méthode iterator est IEnumerable<T>, un type interface itérateur.The return type of the iterator method is IEnumerable<T>, 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.

Sub Main()
    For Each number In Power(2, 8)
        Console.Write(number & " ")
    Next
    ' Output: 2 4 8 16 32 64 128 256
    Console.ReadKey()
End Sub

Private Iterator Function Power(
ByVal base As Integer, ByVal highExponent As Integer) _
As System.Collections.Generic.IEnumerable(Of Integer)

    Dim result = 1

    For counter = 1 To highExponent
        result = result * base
        Yield result
    Next
End Function

ExempleExample

L'exemple suivant illustre un accesseur Get qui est un itérateur.The following example demonstrates a Get accessor that is an iterator. La déclaration de propriété comprend un Iterator modificateur.The property declaration includes an Iterator modifier.

Sub Main()
    Dim theGalaxies As New Galaxies
    For Each theGalaxy In theGalaxies.NextGalaxy
        With theGalaxy
            Console.WriteLine(.Name & "  " & .MegaLightYears)
        End With
    Next
    Console.ReadKey()
End Sub

Public Class Galaxies
    Public ReadOnly Iterator Property NextGalaxy _
    As System.Collections.Generic.IEnumerable(Of Galaxy)
        Get
            Yield New Galaxy With {.Name = "Tadpole", .MegaLightYears = 400}
            Yield New Galaxy With {.Name = "Pinwheel", .MegaLightYears = 25}
            Yield New Galaxy With {.Name = "Milky Way", .MegaLightYears = 0}
            Yield New Galaxy With {.Name = "Andromeda", .MegaLightYears = 3}
        End Get
    End Property
End Class

Public Class Galaxy
    Public Property Name As String
    Public Property MegaLightYears As Integer
End Class

Pour obtenir des exemples supplémentaires, consultez itérateurs.For additional examples, see Iterators.

Voir aussiSee Also

InstructionsStatements