Yield 陳述式 (Visual Basic)Yield Statement (Visual Basic)

將集合的下一個元素傳送至 For Each...Next 語句。Sends the next element of a collection to a For Each...Next statement.


Yield expression  


詞彙Term 定義Definition
expression 必要。Required. 運算式,可以隱含地轉換成包含語句之反覆運算器函數或 Get 存取子的類型 YieldAn expression that is implicitly convertible to the type of the iterator function or Get accessor that contains the Yield statement.


Yield語句一次會傳回集合的一個元素。The Yield statement returns one element of a collection at a time. Yield語句會包含在反覆運算器函式或 Get 存取子中,這會在集合上執行自訂反復專案。The Yield statement is included in an iterator function or Get accessor, which perform custom iterations over a collection.

您可以使用 For Each 的來取用 iterator 函數 ... 下一個語句或 LINQ 查詢。You consume an iterator function by using a For Each...Next Statement or a LINQ query. 迴圈的每個反復專案都會 For Each 呼叫 iterator 函數。Each iteration of the For Each loop calls the iterator function. Yield 反覆運算器函式中到達語句時, expression 會傳回,並保留程式碼中的目前位置。When a Yield statement is reached in the iterator function, expression is returned, and the current location in code is retained. 下一次呼叫 Iterator 函式時,便會從這個位置重新開始執行。Execution is restarted from that location the next time that the iterator function is called.

expression 語句中的類型 Yield 到反覆運算器的傳回類型,都必須有隱含轉換。An implicit conversion must exist from the type of expression in the Yield statement to the return type of the iterator.

您可以使用 Exit FunctionReturn 語句來結束反復專案。You can use an Exit Function or Return statement to end the iteration.

"Yield" 不是保留字,只有在函數或存取子中使用時才具有特殊意義 Iterator Get"Yield" is not a reserved word and has special meaning only when it is used in an Iterator function or Get accessor.

如需 iterator 函數和存取子的詳細資訊 Get ,請參閱反覆運算器。For more information about iterator functions and Get accessors, see Iterators.

Iterator 函數和 Get 存取子Iterator Functions and Get Accessors

反覆運算器函數或存取子的宣告 Get 必須符合下列需求:The declaration of an iterator function or Get accessor must meet the following requirements:

反覆運算器函式不能出現在事件、實例的函數、靜態的函式或靜態的析構函數中。An iterator function cannot occur in an event, instance constructor, static constructor, or static destructor.

Iterator 函數可以是匿名函式。An iterator function can be an anonymous function. 如需詳細資訊,請參閱反覆運算器。For more information, see Iterators.

例外狀況處理Exception Handling

Yield語句可以在 Try Try 的區塊內 ... Catch .。。Finally 語句A Yield statement can be inside a Try block of a Try...Catch...Finally Statement. Try具有語句的區塊 Yield 可以有 Catch 區塊,而且可以有 Finally 區塊。A Try block that has a Yield statement can have Catch blocks, and can have a Finally block.

Yield語句不能在 Catch 區塊或 Finally 區塊內。A Yield statement cannot be inside a Catch block or a Finally block.

如果 For Each 主體(iterator 函式之外)擲回例外狀況, Catch 則不會執行 iterator 函式中的區塊,但 Finally 會執行 iterator 函式中的區塊。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. CatchIterator 函式內的區塊只會攔截反覆運算器函數內所發生的例外狀況。A Catch block inside an iterator function catches only exceptions that occur inside the iterator function.

技術實作Technical Implementation

下列程式碼會從 iterator 函式傳回 IEnumerable (Of String) ,然後逐一查看的元素 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  

對的呼叫 MyIteratorFunction 不會執行函式的主體。The call to MyIteratorFunction doesn't execute the body of the function. 呼叫會改為將 IEnumerable(Of String) 傳回至 elements 變數中。Instead the call returns an IEnumerable(Of String) into the elements variable.

For Each 迴圈的反覆項目上,會針對 MoveNext 呼叫 elements 方法。On an iteration of the For Each loop, the MoveNext method is called for elements. 這個呼叫會執行 MyIteratorFunction 的主體,直到下一個 Yield 陳述式為止。This call executes the body of MyIteratorFunction until the next Yield statement is reached. Yield語句會傳回一個運算式,它不僅會判斷 element 迴圈主體所耗用量的變數值 Current ,也會傳回元素的屬性(也就是) 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).

For Each 迴圈的每個後續反覆項目上,迭代器主體會從上次停止的位置繼續執行,並且在到達 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. For Each當達到 iterator 函數或或語句的結尾時,迴圈 Return Exit Function 就會完成。The For Each loop completes when the end of the iterator function or a Return or Exit Function statement is reached.


下列範例 Yield 中的語句位於For .。。下一個迴圈。The following example has a Yield statement that is inside a For…Next loop. 在中,每個語句主體的每個反復專案 Main 都會建立對 Power iterator 函數的呼叫。Each iteration of the For Each statement body in Main creates a call to the Power iterator function. 每次呼叫 Iterator 函式都會執行下一個 Yield 陳述式,這會在 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.

反覆運算器方法的傳回型別是,也就是 IEnumerable<T> 反覆運算器介面型別。The return type of the iterator method is IEnumerable<T>, an iterator interface type. 呼叫 Iterator 方法時,它會傳回包含數字乘冪的可列舉物件。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 & " ")
    ' Output: 2 4 8 16 32 64 128 256
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
End Function


下列範例將示範本身為迭代器的 Get 存取子。The following example demonstrates a Get accessor that is an iterator. 屬性宣告包含修飾詞 IteratorThe 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
End Sub

Public Class Galaxies
    Public ReadOnly Iterator Property NextGalaxy _
    As System.Collections.Generic.IEnumerable(Of Galaxy)
            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

如需其他範例,請參閱反覆運算器。For additional examples, see Iterators.

另請參閱See also