タスク ベースの非同期パターン (TAP)Task-based Asynchronous Pattern (TAP)

タスク ベースの非同期パターン (TAP) は、任意の非同期操作を表すために使用される System.Threading.Tasks.Task 名前空間の System.Threading.Tasks.Task<TResult> 型および System.Threading.Tasks 型に基づいています。The Task-based Asynchronous Pattern (TAP) is based on the System.Threading.Tasks.Task and System.Threading.Tasks.Task<TResult> types in the System.Threading.Tasks namespace, which are used to represent arbitrary asynchronous operations. TAP は、新規開発に推奨の非同期デザイン パターンです。TAP is the recommended asynchronous design pattern for new development.

名前付け、パラメーター、および戻り値の型Naming, Parameters, and Return Types

TAP では、非同期操作の開始と終了を表すために単一のメソッドが使用されます。TAP uses a single method to represent the initiation and completion of an asynchronous operation. これは、IAsyncResult メソッドと Begin メソッドが必要になる非同期プログラミング モデル (APM または End) パターンや、Async サフィックスの付いたメソッドと、1 つ以上のイベント、イベント ハンドラーのデリゲート型、および EventArg 派生型も必要になるイベント ベースの非同期パターン (EAP) とは対照的です。This is in contrast to the Asynchronous Programming Model (APM or IAsyncResult) pattern, which requires Begin and End methods, and in contrast to the Event-based Asynchronous Pattern (EAP), which requires a method that has the Async suffix and also requires one or more events, event handler delegate types, and EventArg-derived types. TAP の非同期操作は、操作名の後に Async サフィックスが付きます。たとえば、Get 操作の場合は GetAsync になります。Asynchronous methods in TAP include the Async suffix after the operation name; for example, GetAsync for a Get operation. 既に Async サフィックスの付いたメソッド名を含むクラスに TAP メソッドを追加する場合は、代わりに TaskAsync サフィックスを使用します。If you're adding a TAP method to a class that already contains that method name with the Async suffix, use the suffix TaskAsync instead. たとえば、既にクラスに GetAsync メソッドが含まれている場合は、GetTaskAsync という名前を使用します。For example, if the class already has a GetAsync method, use the name GetTaskAsync.

対応する同期メソッドにより void または TResult 型が返されるかどうかに応じて、TAP メソッドは System.Threading.Tasks.Task または System.Threading.Tasks.Task<TResult> を返します。A TAP method returns either a System.Threading.Tasks.Task or a System.Threading.Tasks.Task<TResult>, based on whether the corresponding synchronous method returns void or a type TResult.

TAP メソッドのパラメーターには、対応する同期メソッドと同じパラメーターを、同じ順序で指定する必要があります。The parameters of a TAP method should match the parameters of its synchronous counterpart, and should be provided in the same order. ただし、out パラメーターと ref パラメーターはこの規則に該当せず、すべて回避する必要があります。However, out and ref parameters are exempt from this rule and should be avoided entirely. out パラメーターまたは ref パラメーターで返されるデータは、代わりに複数の値を格納するために、タプルまたはカスタム データ構造を使用して、TResult により返される Task<TResult> の一部として返す必要があります。Any data that would have been returned through an out or ref parameter should instead be returned as part of the TResult returned by Task<TResult>, and should use a tuple or a custom data structure to accommodate multiple values.

タスクの作成、操作、または組み合わせのためだけに使用されるメソッド (メソッド名またはメソッドが属する型の名前でメソッドの非同期の意図が明確な場合) は、この名前付けパターンに従う必要はありません。このようなメソッドは、連結子と呼ばれることもあります。Methods that are devoted exclusively to the creation, manipulation, or combination of tasks (where the asynchronous intent of the method is clear in the method name or in the name of the type to which the method belongs) need not follow this naming pattern; such methods are often referred to as combinators. 連結子の例には、WhenAll および WhenAny があります。詳細については、記事「タスク ベースの非同期パターンの利用」の「タスク ベースの組み込み連結子の使用」セクションを参照してください。Examples of combinators include WhenAll and WhenAny, and are discussed in the Using the Built-in Task-based Combinators section of the article Consuming the Task-based Asynchronous Pattern.

非同期プログラミング モデル (APM) やイベント ベースの非同期パターン (EAP) など、従来の非同期プログラミング パターンで使用される構文とは異なる TAP 構文の例については、「非同期プログラミングのパターン」を参照してください。For examples of how the TAP syntax differs from the syntax used in legacy asynchronous programming patterns such as the Asynchronous Programming Model (APM) and the Event-based Asynchronous Pattern (EAP), see Asynchronous Programming Patterns.

非同期操作の開始Initiating an Asynchronous Operation

TAP に基づく非同期メソッドは、引数の検証や非同期操作の開始などの少量の作業を同期をとって実行してから結果のタスクを返すことができます。An asynchronous method that is based on TAP can do a small amount of work synchronously, such as validating arguments and initiating the asynchronous operation, before it returns the resulting task. このような同期作業は必要最低限にし、非同期メソッドからすぐに制御を戻すようにします。Synchronous work should be kept to the minimum so the asynchronous method can return quickly. 制御をすぐに戻す理由は次のとおりです。Reasons for a quick return include the following:

  • 非同期メソッドはユーザー インターフェイス (UI) スレッドから呼び出される可能性があるため、同期作業の実行に時間がかかると、アプリケーションの応答性が低下します。Asynchronous methods may be invoked from user interface (UI) threads, and any long-running synchronous work could harm the responsiveness of the application.

  • 複数の非同期メソッドが同時に起動される可能性があります。Multiple asynchronous methods may be launched concurrently. そのため、非同期メソッドの同期部分の作業に時間がかかると、他の非同期操作の開始が遅れ、同時実行の利点が低減します。Therefore, any long-running work in the synchronous portion of an asynchronous method could delay the initiation of other asynchronous operations, thereby decreasing the benefits of concurrency.

場合によっては、操作の完了に必要な作業の量は、操作を非同期に起動するのに必要な作業量よりも少なくなります。In some cases, the amount of work required to complete the operation is less than the amount of work required to launch the operation asynchronously. このようなシナリオの例にはストリームからの読み取りがあり、既にメモリ バッファーにあるデータを読み取ることで読み取り操作が完了する場合です。Reading from a stream where the read operation can be satisfied by data that is already buffered in memory is an example of such a scenario. このような場合は、操作を同期をとって実行し、既に完了しているタスクを返すことができます。In such cases, the operation may complete synchronously, and may return a task that has already been completed.

例外Exceptions

非同期メソッドは、使用エラーに応答して非同期メソッド呼び出しからスローされる例外のみを発生する必要があります。An asynchronous method should raise an exception to be thrown out of the asynchronous method call only in response to a usage error. 運用コードでは使用エラーを発生させないようにする必要があります。Usage errors should never occur in production code. たとえば、null 参照 (Visual Basic では Nothing) がメソッドの引数の 1 つとして渡されたときにエラー状態 (通常 ArgumentNullException によって表される) が発生する場合、呼び出し元のコードを変更して null 参照が渡されないようにします。For example, if passing a null reference (Nothing in Visual Basic) as one of the method’s arguments causes an error state (usually represented by an ArgumentNullException exception), you can modify the calling code to ensure that a null reference is never passed. 他のエラーの場合はすべて、非同期メソッドの実行中に発生する例外を、返されるタスクに割り当てます。これは、タスクが返される前に非同期メソッドが同期をとって行われる場合でも同じです。For all other errors, exceptions that occur when an asynchronous method is running should be assigned to the returned task, even if the asynchronous method happens to complete synchronously before the task is returned. 通常、タスクに含まれる例外は最大でも 1 つです。Typically, a task contains at most one exception. ただし、タスクが複数の操作 (WhenAll など) を表す場合は、複数の例外を単一タスクに関連付けることができます。However, if the task represents multiple operations (for example, WhenAll), multiple exceptions may be associated with a single task.

対象の環境Target Environment

TAP メソッドを実装するときに、非同期実行をどこで行うかを決定できます。When you implement a TAP method, you can determine where asynchronous execution occurs. スレッド プールで作業負荷を実行したり、(操作実行のほとんどでスレッドにバインドされないように) 非同期 I/O を使用して実装したり、特定のスレッド (UI スレッドなど) で実行したり、任意の数の可能なコンテキストを使用したりすることができます。You may choose to execute the workload on the thread pool, implement it by using asynchronous I/O (without being bound to a thread for the majority of the operation’s execution), run it on a specific thread (such as the UI thread), or use any number of potential contexts. TAP メソッドは何も実行せず、システムの他の場所で発生した何らかの条件を表す Task を返すのみの場合もあります (待ち行列データ構造に届いたデータを表すタスクなど)。A TAP method may even have nothing to execute, and may just return a Task that represents the occurrence of a condition elsewhere in the system (for example, a task that represents data arriving at a queued data structure).

TAP メソッドの呼び出し元は、結果的に生成されるタスクに同期的に応答することで、TAP メソッドの完了を待つことをブロックできます。あるいは、非同期操作の完了時に追加 (継続) コードを実行できます。The caller of the TAP method may block waiting for the TAP method to complete by synchronously waiting on the resulting task, or may run additional (continuation) code when the asynchronous operation completes. 継続コードの作成者は、そのコードが実行される場所を制御できます。The creator of the continuation code has control over where that code executes. 継続コードは、Task クラス (ContinueWith など) のメソッドによって明示的に作成するか、継続の上位にビルドされる言語サポート (C# の await、Visual Basic の Await、F# の AwaitValue など) を使用して暗黙のうちに作成できます。You may create the continuation code either explicitly, through methods on the Task class (for example, ContinueWith) or implicitly, by using language support built on top of continuations (for example, await in C#, Await in Visual Basic, AwaitValue in F#).

タスク ステータスTask Status

Task クラスは、非同期操作の有効期間を提供し、そのサイクルは、TaskStatus 列挙型によって表されます。The Task class provides a life cycle for asynchronous operations, and that cycle is represented by the TaskStatus enumeration. Task および Task<TResult> から派生する型のコーナー ケースに加え、スケジューリングからの構造の分離をサポートするために、Task クラスは Start メソッドを公開します。To support corner cases of types that derive from Task and Task<TResult>, and to support the separation of construction from scheduling, the Task class exposes a Start method. Task パブリック コンストラクターにより作成されるタスクは、ライフ サイクルがスケジュールされていない Created 状態から始まり、これらのインスタンスで Start が呼び出されるときにのみスケジュールされることから、コールド タスクと呼ばれます。Tasks that are created by the public Task constructors are referred to as cold tasks, because they begin their life cycle in the non-scheduled Created state and are scheduled only when Start is called on these instances.

他のすべてのタスクは、ホットな状態からライフ サイクルが始まります。つまり、タスクが表す非同期操作が既に開始され、それらのタスクの状態は TaskStatus.Created 以外の列挙値であることを意味します。All other tasks begin their life cycle in a hot state, which means that the asynchronous operations they represent have already been initiated and their task status is an enumeration value other than TaskStatus.Created. TAP メソッドから返されるすべてのタスクをアクティブにする必要があります。All tasks that are returned from TAP methods must be activated. TAP メソッドが返すタスクをインスタンス化するためにタスクのコンストラクターを内部使用する場合、TAP メソッドはタスクを返す前に Task オブジェクトで Start を呼び出す必要があります。If a TAP method internally uses a task’s constructor to instantiate the task to be returned, the TAP method must call Start on the Task object before returning it. TAP メソッドのコンシューマーは、返されたタスクがアクティブであるものと推定しても問題はなく、TAP メソッドから返された Start 上で Task 呼び出しを試行しないようにする必要があります。Consumers of a TAP method may safely assume that the returned task is active and should not try to call Start on any Task that is returned from a TAP method. アクティブなタスク上で Start を呼び出すと、InvalidOperationException 例外になります。Calling Start on an active task results in an InvalidOperationException exception.

取り消し (省略可能)Cancellation (Optional)

TAP では、取り消しは非同期メソッドの実装側とコンシューマーのどちらでも省略可能です。In TAP, cancellation is optional for both asynchronous method implementers and asynchronous method consumers. 操作の取り消しを許可する場合、キャンセル トークン (CancellationToken インスタンス) を受け取る非同期メソッドのオーバーロードを公開します。If an operation allows cancellation, it exposes an overload of the asynchronous method that accepts a cancellation token (CancellationToken instance). 規則により、パラメーターには cancellationToken という名前が付けられます。By convention, the parameter is named cancellationToken.

public Task ReadAsync(byte [] buffer, int offset, int count, 
                      CancellationToken cancellationToken)
Public Function ReadAsync(buffer() As Byte, offset As Integer, 
                          count As Integer, 
                          cancellationToken As CancellationToken) _ 
                          As Task

非同期操作は取り消し要求に対してこのトークンを監視します。The asynchronous operation monitors this token for cancellation requests. 取り消し要求を受け取ると、その要求を受け入れて操作を取り消すことができます。If it receives a cancellation request, it may choose to honor that request and cancel the operation. 取り消し要求によって作業が途中で終了する場合、TAP メソッドは Canceled 状態で終了するタスクを返します。使用できる結果はなく、例外もスローされません。If the cancellation request results in work being ended prematurely, the TAP method returns a task that ends in the Canceled state; there is no available result and no exception is thrown. Canceled 状態は、Faulted 状態や RanToCompletion 状態と共に、タスクの最終状態 (完了状態) と見なされます。The Canceled state is considered to be a final (completed) state for a task, along with the Faulted and RanToCompletion states. したがって、タスクが Canceled 状態の場合、IsCompleted プロパティは true を返します。Therefore, if a task is in the Canceled state, its IsCompleted property returns true. タスクが Canceled 状態で完了した場合、NotOnCanceled など、継続のオプションを継続から除外するよう指定されていない限り、タスクに登録された継続がスケジュールまたは実行されます。When a task completes in the Canceled state, any continuations registered with the task are scheduled or executed, unless a continuation option such as NotOnCanceled was specified to opt out of continuation. 言語機能を使用して取り消されたタスクを非同期に待機するコードは実行を継続しますが、OperationCanceledException またはその派生例外を受け取ります。Any code that is asynchronously waiting for a canceled task through use of language features continues to run but receives an OperationCanceledException or an exception derived from it. WaitWaitAll などのメソッドによってタスクでの同期をとって待機している状態をブロックされたコードも、例外を伴って実行を継続します。Code that is blocked synchronously waiting on the task through methods such as Wait and WaitAll also continue to run with an exception.

キャンセル トークンが、トークンを受け取る TAP メソッドが呼び出される前に取り消しを要求していた場合、TAP メソッドは Canceled タスクを返す必要があります。If a cancellation token has requested cancellation before the TAP method that accepts that token is called, the TAP method should return a Canceled task. ただし、非同期操作の実行中に取り消し要求が出される場合、その非同期操作は取り消し要求を受け取る必要はありません。However, if cancellation is requested while the asynchronous operation is running, the asynchronous operation need not accept the cancellation request. 取り消し要求の結果として操作が完了した場合にのみ、返されたタスクが Canceled 状態で終了します。The returned task should end in the Canceled state only if the operation ends as a result of the cancellation request. 取り消しが要求されても、結果 (例外) が依然として生成される場合、タスクは RanToCompletion 状態または Faulted 状態で終了します。If cancellation is requested but a result or an exception is still produced, the task should end in the RanToCompletion or Faulted state.

何よりもまずキャンセルできる機能を公開することが望まれる非同期メソッドの場合、キャンセル トークンを受け取らないオーバーロードを用意する必要はありません。For asynchronous methods that want to expose the ability to be cancelled first and foremost, you don't have to provide an overload that doesn’t accept a cancellation token. 取り消せないメソッドの場合、キャンセル トークンを受け取るオーバーロードを用意しません。これにより、ターゲット メソッドが実際に取り消し可能かどうかを呼び出し元に示すことができます。For methods that cannot be canceled, do not provide overloads that accept a cancellation token; this helps indicate to the caller whether the target method is actually cancelable. 取り消しを望まないコンシューマー コードは、CancellationToken を受け取るメソッドを呼び出し、引数値として None を指定することができます。Consumer code that does not desire cancellation may call a method that accepts a CancellationToken and provide None as the argument value. None は、既定の CancellationToken と機能的には同じです。None is functionally equivalent to the default CancellationToken.

進行状況のレポート (省略可能)Progress Reporting (Optional)

一部の非同期操作では、進行状況の通知を行うことで利点が得られます。進行状況の通知は、通常、非同期操作の進行状況に関する情報でユーザー インターフェイスを更新するために使用されます。Some asynchronous operations benefit from providing progress notifications; these are typically used to update a user interface with information about the progress of the asynchronous operation.

TAP では、進行状況が、通常 IProgress<T> という名前のパラメーターとして非同期メソッドに渡される progress インターフェイスによって処理されます。In TAP, progress is handled through an IProgress<T> interface, which is passed to the asynchronous method as a parameter that is usually named progress. 非同期メソッドの呼び出し時に進行状況インターフェイスを指定することで、不適切な使用方法により発生する競合状態 (操作の開始後に不適切に登録されたイベント ハンドラーで更新を検出できない場合) を排除できます。Providing the progress interface when the asynchronous method is called helps eliminate race conditions that result from incorrect usage (that is, when event handlers that are incorrectly registered after the operation starts may miss updates). さらに重要なのは、コンシューマー コードの判断に応じて、進行状況インターフェイスがさまざまな実装方法の進行状況をサポートできるようにすることです。More importantly, the progress interface supports varying implementations of progress, as determined by the consuming code. たとえば、コンシューマー コードが最新の進行状況の更新のみに留意する場合、すべての更新をバッファーに格納することを望む場合、各更新の操作を呼び出すことを望む場合、呼び出しを特定のスレッドにマーシャリングするかどうかの制御を望む場合が考えられます。For example, the consuming code may only care about the latest progress update, or may want to buffer all updates, or may want to invoke an action for each update, or may want to control whether the invocation is marshaled to a particular thread. これらはすべて、インターフェイスの異なる実装を使用して行うことができ、各実装を特定のコンシューマー ニーズに合わせてカスタマイズできます。All these options may be achieved by using a different implementation of the interface, customized to the particular consumer’s needs. 取り消しと同様、TAP の実装では、API が進行状況通知をサポートする場合にのみ、IProgress<T> パラメーターを指定する必要があります。As with cancellation, TAP implementations should provide an IProgress<T> parameter only if the API supports progress notifications.

たとえば、前に説明した ReadAsync メソッドが読み取り済みのバイト数の形式で中間進行状況を報告できる場合、進行状況のコールバックは IProgress<T> インターフェイスとなることが考えられます。For example, if the ReadAsync method discussed earlier in this article is able to report intermediate progress in the form of the number of bytes read thus far, the progress callback could be an IProgress<T> interface:

public Task ReadAsync(byte[] buffer, int offset, int count, 
                      IProgress<long> progress)
Public Function ReadAsync(buffer() As Byte, offset As Integer, 
                          count As Integer, 
                          progress As IProgress(Of Long)) As Task 

FindFilesAsync メソッドが特定の検索パターンに合ったすべてのファイルのリストを返す場合は、進行状況のコールバックで、完了した作業の割合の見積りに加え、現在の部分的な結果セットを示すことが考えられます。If a FindFilesAsync method returns a list of all files that meet a particular search pattern, the progress callback could provide an estimate of the percentage of work completed as well as the current set of partial results. これは、タプルで行ったり、It could do this either with a tuple:

public Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
            string pattern, 
            IProgress<Tuple<double, 
            ReadOnlyCollection<List<FileInfo>>>> progress)
Public Function FindFilesAsync(pattern As String, 
                               progress As IProgress(Of Tuple(Of Double, ReadOnlyCollection(Of List(Of FileInfo))))) _
                               As  Task(Of ReadOnlyCollection(Of FileInfo))

または次のように API 固有のデータ型で行うことができます。or with a data type that is specific to the API:

public Task<ReadOnlyCollection<FileInfo>> FindFilesAsync(
    string pattern, 
    IProgress<FindFilesProgressInfo> progress)
Public Function FindFilesAsync(pattern As String, 
                               progress As IProgress(Of FindFilesProgressInfo)) _
                               As Task(Of ReadOnlyCollection(Of FileInfo))

後者の場合、特別なデータ型には通常 ProgressInfo サフィックスを付けます。In the latter case, the special data type is usually suffixed with ProgressInfo.

TAP の実装が progress パラメーターを受け取るオーバーロードを用意している場合、null の引数を許可し、進行状況を報告しないことを許可する必要があります。If TAP implementations provide overloads that accept a progress parameter, they must allow the argument to be null, in which case no progress will be reported. TAP の実装は、Progress<T> オブジェクトに進行状況を同期をとって報告して、非同期メソッドが速やかに進行状況を提供し、進行状況のコンシューマーが、最適な情報の処理方法と処理場所を判断できるようにします。TAP implementations should report the progress to the Progress<T> object synchronously, which enables the asynchronous method to quickly provide progress, and allow the consumer of the progress to determine how and where best to handle the information. たとえば、進行状況のインスタンスはコールバックをマーシャリングし、キャプチャされた同期コンテキストでイベントを発生するように選択することができます。For example, the progress instance could choose to marshal callbacks and raise events on a captured synchronization context.

IProgress<T> の実装IProgress<T> Implementations

.NET Framework 4.5.NET Framework 4.5 は、単一の IProgress<T> implementation: Progress<T> 実装を提供します。The .NET Framework 4.5.NET Framework 4.5 provides a single IProgress<T> implementation: Progress<T>. Progress<T> クラスは次のように宣言されます。The Progress<T> class is declared as follows:

public class Progress<T> : IProgress<T>  
{  
    public Progress();  
    public Progress(Action<T> handler);  
    protected virtual void OnReport(T value);  
    public event EventHandler<T> ProgressChanged;  
}  
Public Class Progress(Of T) : Inherits IProgress(Of T)  
    Public Sub New()  
    Public Sub New(handler As Action(Of T))  
    Protected Overridable Sub OnReport(value As T)  
    Public Event ProgressChanged As EventHandler(Of T>  
End Class  

Progress<T> のインスタンスは、非同期操作が進行状況の更新を報告するたびに発生する ProgressChanged イベントを公開します。An instance of Progress<T> exposes a ProgressChanged event, which is raised every time the asynchronous operation reports a progress update. ProgressChanged イベントは、SynchronizationContext インスタンスがインスタンス化されたときにキャプチャされた Progress<T> オブジェクトで発生します。The ProgressChanged event is raised on the SynchronizationContext object that was captured when the Progress<T> instance was instantiated. 同期コンテキストを利用できない場合は、スレッド プールをターゲットとして、既定のコンテキストが使用されます。If no synchronization context was available, a default context that targets the thread pool is used. ハンドラーは、このイベントに登録することができます。Handlers may be registered with this event. 1 つのハンドラーは、利便性のために Progress<T> コンストラクターにも提供でき、ProgressChanged イベントのイベント ハンドラーと同様に作動します。A single handler may also be provided to the Progress<T> constructor for convenience, and behaves just like an event handler for the ProgressChanged event. 進行状況の更新は、イベント ハンドラーの実行中、非同期操作を遅延しないように、非同期に発生します。Progress updates are raised asynchronously to avoid delaying the asynchronous operation while event handlers are executing. 別のセマンティクスを適用するため、別の IProgress<T> の実装を選択できます。Another IProgress<T> implementation could choose to apply different semantics.

提供するオーバーロードの選択Choosing the Overloads to Provide

ともに省略可能な CancellationToken パラメーターと IProgress<T> パラメーターの両方を TAP の実装に使用すると、4 つまでオーバーロードを要求することができます。If a TAP implementation uses both the optional CancellationToken and optional IProgress<T> parameters, it could potentially require up to four overloads:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, CancellationToken cancellationToken);  
public Task MethodNameAsync(…, IProgress<T> progress);   
public Task MethodNameAsync(…,   
    CancellationToken cancellationToken, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken cancellationToken) As Task  
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task   
Public MethodNameAsync(…, cancellationToken As CancellationToken,   
                       progress As IProgress(Of T)) As Task  

ただし、TAP の実装の多くは取り消しまたは進行状況の機能を提供しないため、必要なメソッドは 1 つです。However, many TAP implementations provide neither cancellation or progress capabilities, so they require a single method:

public Task MethodNameAsync(…);  
Public MethodNameAsync(…) As Task  

TAP の実装で取り消しまたは進行状況の両方ではなく、いずれかを一方をサポートする場合は、実装に 2 つのオーバーロードを提供することができます。If a TAP implementation supports either cancellation or progress but not both, it may provide two overloads:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, CancellationToken cancellationToken);  

// … or …  

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken) As Task  

' … or …  

Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, progress As IProgress(Of T)) As Task  

TAP の実装で取り消しおよび進行状況の両方をサポートする場合は、4 種類のオーバーロードをすべて公開できます。If a TAP implementation supports both cancellation and progress, it may expose all four overloads. ただし、次の 2 種類のみ提供することもできます。However, it may provide only the following two:

public Task MethodNameAsync(…);  
public Task MethodNameAsync(…,   
    CancellationToken cancellationToken, IProgress<T> progress);  
Public MethodNameAsync(…) As Task  
Public MethodNameAsync(…, cancellationToken As CancellationToken,   
                       progress As IProgress(Of T)) As Task  

不足する 2 種類の中間の組み合わせを補足するために、開発者は None パラメーターに CancellationToken または既定の cancellationToken を渡したり、null パラメーターに progress を渡すことができます。To compensate for the two missing intermediate combinations, developers may pass None or a default CancellationToken for the cancellationToken parameter and null for the progress parameter.

TAP メソッドに必ず取り消しや進行状況をサポートすることを想定する場合、必要なパラメーターを受け取らないオーバーロードは省略できます。If you expect every usage of the TAP method to support cancellation or progress, you may omit the overloads that don’t accept the relevant parameter.

TAP メソッドの複数のオーバーロードを公開して取り消しや進行状況を省略可能にする場合、取り消しや進行状況をサポートしないオーバーロードは、これらをサポートするオーバーロードに、取り消しの場合は None、進行状況の場合は null が渡されたように機能する必要があります。If you decide to expose multiple overloads to make cancellation or progress optional, the overloads that don’t support cancellation or progress should behave as if they passed None for cancellation or null for progress to the overload that does support these.

TitleTitle 説明Description
非同期プログラミングのパターンAsynchronous Programming Patterns 非同期操作を実行するための 3 種類のパターンとして、タスク ベースの非同期パターン (TAP)、非同期プログラミング モデル (APM)、およびイベント ベースの非同期パターン (EAP) を紹介します。Introduces the three patterns for performing asynchronous operations: the Task-based Asynchronous Pattern (TAP), the Asynchronous Programming Model (APM), and the Event-based Asynchronous Pattern (EAP).
タスク ベースの非同期パターンの実装Implementing the Task-based Asynchronous Pattern タスク ベースの非同期パターン (TAP) の実装の 3 つの方法として、Visual Studio の C# および Visual Basic コンパイラを使用する方法、手動で行う方法、またはコンパイラと手動による方法を組み合わせた方法を説明します。Describes how to implement the Task-based Asynchronous Pattern (TAP) in three ways: by using the C# and Visual Basic compilers in Visual Studio, manually, or through a combination of the compiler and manual methods.
タスク ベースの非同期パターンの利用Consuming the Task-based Asynchronous Pattern タスクとコールバックを使用して、ブロックすることなく待機できる方法を説明します。Describes how you can use tasks and callbacks to achieve waiting without blocking.
他の非同期パターンと型との相互運用Interop with Other Asynchronous Patterns and Types タスク ベースの非同期パターン (TAP) を使用して、非同期プログラミング モデル (APM) とイベント ベースの非同期パターン (EAP) を実装する方法について説明します。Describes how to use the Task-based Asynchronous Pattern (TAP) to implement the Asynchronous Programming Model (APM) and Event-based Asynchronous Pattern (EAP).