ValueTask<TResult> 結構


提供包裝 Task<TResult>TResult 的實值型別,只會使用其中之一。Provides a value type that wraps a Task<TResult> and a TResult, only one of which is used.

generic <typename TResult>
public value class ValueTask : IEquatable<System::Threading::Tasks::ValueTask<TResult>>
public struct ValueTask<TResult> : IEquatable<System.Threading.Tasks.ValueTask<TResult>>
type ValueTask<'Result> = struct
Public Structure ValueTask(Of TResult)
Implements IEquatable(Of ValueTask(Of TResult))



結果。The result.



ValueTask<TResult> 實例可能會等候或轉換成使用 AsTaskTask<TResult>A ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. ValueTask<TResult> 實例可能只會等候一次,而且取用者可能不會呼叫 GetAwaiter(),直到實例完成為止。A ValueTask<TResult> instance may only be awaited once, and consumers may not call GetAwaiter() until the instance has completed. 如果無法接受這些限制,請呼叫 AsTask,將 ValueTask<TResult> 轉換成 Task<TResult>If these limitations are unacceptable, convert the ValueTask<TResult> to a Task<TResult> by calling AsTask.

下列作業永遠不應在 ValueTask<TResult> 實例上執行:The following operations should never be performed on a ValueTask<TResult> instance:

  • 等候實例多次。Awaiting the instance multiple times.
  • 多次呼叫 AsTaskCalling AsTask multiple times.
  • 當作業尚未完成或多次使用時,使用 .Result.GetAwaiter().GetResult()Using .Result or .GetAwaiter().GetResult() when the operation hasn't yet completed, or using them multiple times.
  • 使用其中一種以上的方法來取用實例。Using more than one of these techniques to consume the instance.

如果您執行上述任何一個動作,則結果會是未定義的。If you do any of the above, the results are undefined.

當方法可能會以同步方式取得其作業的結果,而且預期被叫用時,如果為每個呼叫配置新的 Task<TResult> 的成本會很過,就可能會傳回此實數值型別的實例。A method may return an instance of this value type when it's likely that the result of its operation will be available synchronously, and when it's expected to be invoked so frequently that the cost of allocating a new Task<TResult> for each call will be prohibitive.

使用 ValueTask<TResult> 而非 Task<TResult>,會有取捨。There are tradeoffs to using a ValueTask<TResult> instead of a Task<TResult>. 例如,雖然在成功的結果可同步使用的情況下,ValueTask<TResult> 有助於避免配置,但它也包含多個欄位,而 Task<TResult> 做為參考型別是單一欄位。For example, while a ValueTask<TResult> can help avoid an allocation in the case where the successful result is available synchronously, it also contains multiple fields, whereas a Task<TResult> as a reference type is a single field. 這表示從方法傳回 ValueTask<TResult> 會導致複製更多資料。This means that returning a ValueTask<TResult> from a method results in copying more data. 這也表示,如果傳回 ValueTask<TResult> 的方法在非同步方法中等候,則該非同步方法的狀態機器將會較大,因為它必須儲存包含多個欄位的結構,而不是單一參考。It also means, that if a method that returns a ValueTask<TResult> is awaited within an async method, the state machine for that async method will be larger, because it must store a struct containing multiple fields instead of a single reference.

對於使用 await 來取用非同步作業的結果,ValueTask<TResult> 可能會導致更複雜的程式設計模型,而需要更多的配置。For uses other than consuming the result of an asynchronous operation using await, ValueTask<TResult> can lead to a more convoluted programming model that requires more allocations. 例如,假設有一個方法可以傳回具有快取工作的 Task<TResult> 做為通用結果或 ValueTask<TResult>For example, consider a method that could return either a Task<TResult> with a cached task as a common result or a ValueTask<TResult>. 如果結果的取用者想要在 WhenAllWhenAny之類的方法中使用它做為 Task<TResult>,則必須先將 ValueTask<TResult> 轉換成使用 Task<TResult>AsTask,而導致在第一個位置使用快取的 Task<TResult> 時,會避免的配置。If the consumer of the result wants to use it as a Task<TResult> in a method like WhenAll or WhenAny, the ValueTask<TResult> must first be converted to a Task<TResult> using AsTask, leading to an allocation that would have been avoided if a cached Task<TResult> had been used in the first place.

因此,任何非同步方法的預設選擇都應該要傳回 TaskTask<TResult>As such, the default choice for any asynchronous method should be to return a Task or Task<TResult>. 只有當效能分析證明使用 ValueTask<TResult> 而不是 Task<TResult>時,才需要這麼做。Only if performance analysis proves it worthwhile should a ValueTask<TResult> be used instead of a Task<TResult>. 在大部分的情況下,不建議使用非泛型版本的 ValueTaskThe non generic version of ValueTask is not recommended for most scenarios. CompletedTask 屬性應該用來在方法傳回 Task 同步且成功完成的情況下,回復成功完成的 singleton。The CompletedTask property should be used to hand back a successfully completed singleton in the case where a method returning a Task completes synchronously and successfully.


從C# 7.0 開始就支援使用 ValueTask<TResult> 類型,而且任何 Visual Basic 版本都不支援。The use of the ValueTask<TResult> type is supported starting with C# 7.0, and is not supported by any version of Visual Basic.


ValueTask<TResult>(IValueTaskSource<TResult>, Int16)

使用代表作業的 ValueTask<TResult> 物件初始化 IValueTaskSource<TResult> 類別的新執行個體。Initializes a new instance of the ValueTask<TResult> class with a IValueTaskSource<TResult> object that represents the operation.


使用所提供之代表作業的工作,初始化 ValueTask<TResult> 類別的新執行個體。Initializes a new instance of the ValueTask<TResult> class using the supplied task that represents the operation.


使用所提供之成功作業的結果,初始化 ValueTask<TResult> 類別的新執行個體。Initializes a new instance of the ValueTask<TResult> class using the supplied result of a successful operation.



取得值,指出這個物件是否代表已取消的作業。Gets a value that indicates whether this object represents a canceled operation.


取得值,指出這個物件是否代表已完成的作業。Gets a value that indicates whether this object represents a completed operation.


取得值,指出這個物件是否代表已成功完成的作業。Gets a value that indicates whether this object represents a successfully completed operation.


取得值,指出這個物件是否代表失敗的作業。Gets a value that indicates whether this object represents a failed operation.


取得結果。Gets the result.



擷取代表這個 Task<TResult>ValueTask<TResult> 物件。Retrieves a Task<TResult> object that represents this ValueTask<TResult>.


設定此值的 awaiter。Configures an awaiter for this value.


建立搭配非同步方法使用的方法產生器。Creates a method builder for use with an async method.


判斷指定的物件是否等於目前的物件。Determines whether the specified object is equal to the current object.


判斷指定的 ValueTask<TResult> 物件是否等於目前的 ValueTask<TResult> 物件。Determines whether the specified ValueTask<TResult> object is equal to the current ValueTask<TResult> object.


建立此值的 awaiter。Creates an awaiter for this value.


傳回這個執行個體的雜湊碼。Returns the hash code for this instance.


取得未來可以隨時使用的 ValueTask<TResult>Gets a ValueTask<TResult> that may be used at any point in the future.


傳回代表目前物件的字串。Returns a string that represents the current object.


Equality(ValueTask<TResult>, ValueTask<TResult>)

比較兩個值是否相等。Compares two values for equality.

Inequality(ValueTask<TResult>, ValueTask<TResult>)

判斷兩個 ValueTask<TResult> 值是否不相等。Determines whether two ValueTask<TResult> values are unequal.