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>实例可以等待或使用转换为 Task<TResult> AsTaskA ValueTask<TResult> instance may either be awaited or converted to a Task<TResult> using AsTask. ValueTask<TResult>实例仅可等待一次,并且 Result 在实例完成之前,使用者可能无法读取。A ValueTask<TResult> instance may only be awaited once, and consumers may not read Result until the instance has completed. 如果这些限制不可接受,请 ValueTask<TResult> Task<TResult> 通过调用将转换为 AsTaskIf 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.
  • AsTask多次调用。Calling 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>. 如果该结果的使用者想要 Task<TResult> 在类似于或的方法中将其用作 WhenAll WhenAny ,则 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>. ValueTask大多数情况下,不建议使用的非泛型版本。The non generic version of ValueTask is not recommended for most scenarios. CompletedTask此属性应该用于在方法返回成功完成的情况下,手动返回已成功完成的单一实例 TaskThe 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.


ValueTask<TResult>支持使用类型,从 c # 7.0 开始,不受 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)

使用表示操作的 IValueTaskSource<TResult> 对象初始化 ValueTask<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.



检索表示此 ValueTask<TResult>Task<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.