async (C# リファレンス)async (C# Reference)

async 修飾子を使用して、メソッド、ラムダ式、または匿名メソッドが非同期であることを指定します。Use the async modifier to specify that a method, lambda expression, or anonymous method is asynchronous. この修飾子が使用されているメソッドまたは式を、"非同期メソッド" と呼びます。If you use this modifier on a method or expression, it's referred to as an async method. 次の例では、ExampleMethodAsync という名前の非同期メソッドを定義します。The following example defines an async method named ExampleMethodAsync:

public async Task<int> ExampleMethodAsync()  
{  
    // . . . .  
}  

非同期プログラミングに慣れていない場合、または、非同期メソッドで await キーワードを使って、実行時間が長くなる可能性のある処理を、呼び出し元のスレッドをブロックすることなく実行する方法を理解していない場合は、「Async および Await を使用した非同期プログラミング」の概要をご覧ください。If you're new to asynchronous programming or do not understand how an async method uses the await keyword to do potentially long-running work without blocking the caller’s thread, read the introduction in Asynchronous Programming with async and await. 次のコードは、非同期メソッド内のコードで、HttpClient.GetStringAsync メソッドを呼び出します。The following code is found inside an async method and calls the HttpClient.GetStringAsync method:

string contents = await httpClient.GetStringAsync(requestUrl);  

非同期メソッドは、最初の await 式に到達するまで同期的に実行されますが、この時点で、待機していたタスクが完了するまで中断されます。An async method runs synchronously until it reaches its first await expression, at which point the method is suspended until the awaited task is complete. 次のセクションの例で示すように、その間はメソッドの呼び出し元に制御が戻ります。In the meantime, control returns to the caller of the method, as the example in the next section shows.

async キーワードで修飾されているメソッドに await 式またはステートメントが含まれていない場合、メソッドは同期的に実行されます。If the method that the async keyword modifies doesn't contain an await expression or statement, the method executes synchronously. await ステートメントが含まれていない非同期メソッドが存在する場合は、その状態がエラーを示す可能性があるため、コンパイラによって警告が通知されます。A compiler warning alerts you to any async methods that don't contain await statements, because that situation might indicate an error. コンパイラの警告 (レベル 1) CS4014」をご覧ください。See Compiler Warning (level 1) CS4014.

async は、メソッド、ラムダ式、または匿名メソッドを修飾する場合にのみキーワードとなるため、コンテキスト キーワードです。The async keyword is contextual in that it's a keyword only when it modifies a method, a lambda expression, or an anonymous method. それ以外の場合は、識別子として解釈されます。In all other contexts, it's interpreted as an identifier.

Example

次の例は、非同期のイベント ハンドラー StartButton_Click と非同期メソッド ExampleMethodAsync との間の制御構造および制御フローを示しています。The following example shows the structure and flow of control between an async event handler, StartButton_Click, and an async method, ExampleMethodAsync. 非同期メソッドの結果は、Web ページの文字数です。The result from the async method is the number of characters of a web page. このコードは、Visual Studio で Windows Presentation Foundation (WPF) アプリまたは Windows ストア アプリを作成する場合に適しています。アプリの設定に関するコード内のコメントを参照してください。The code is suitable for a Windows Presentation Foundation (WPF) app or Windows Store app that you create in Visual Studio; see the code comments for setting up the app.

このコードは、Visual Studio で、Windows Presentation Foundation (WPF) アプリまたは Windows ストア アプリとして実行できます。You can run this code in Visual Studio as a Windows Presentation Foundation (WPF) app or a Windows Store app. StartButton という名前のボタン コントロールと、ResultsTextBox という名前のテキストボックス コントロールが必要です。You need a Button control named StartButton and a Textbox control named ResultsTextBox. 次のように、名前とハンドラーを必ず設定してください。Remember to set the names and handler so that you have something like this:

<Button Content="Button" HorizontalAlignment="Left" Margin="88,77,0,0" VerticalAlignment="Top" Width="75"  
        Click="StartButton_Click" Name="StartButton"/>  
<TextBox HorizontalAlignment="Left" Height="137" Margin="88,140,0,0" TextWrapping="Wrap"   
         Text="&lt;Enter a URL&gt;" VerticalAlignment="Top" Width="310" Name="ResultsTextBox"/>  

WPF アプリとしてコードを実行するには:To run the code as a WPF app:

  • 次のコードを、MainWindow.xaml.cs の MainWindow クラスに貼り付けます。Paste this code into the MainWindow class in MainWindow.xaml.cs.
  • System.Net.Http に対する参照を追加します。Add a reference to System.Net.Http.
  • System.Net.Http に対する using ディレクティブを追加します。Add a using directive for System.Net.Http.

Windows ストア アプリとしてコードを実行するには:To run the code as a Windows Store app:

  • 次のコードを、MainPage.xaml.cs の MainPage クラスに貼り付けます。Paste this code into the MainPage class in MainPage.xaml.cs.
  • System.Net.Http と System.Threading.Tasks に対する using ディレクティブを追加します。Add using directives for System.Net.Http and System.Threading.Tasks.
private async void StartButton_Click(object sender, RoutedEventArgs e)
{
    // ExampleMethodAsync returns a Task<int>, which means that the method  
    // eventually produces an int result. However, ExampleMethodAsync returns  
    // the Task<int> value as soon as it reaches an await.  
    ResultsTextBox.Text += "\n";

    try
    {
        int length = await ExampleMethodAsync();
        // Note that you could put "await ExampleMethodAsync()" in the next line where  
        // "length" is, but due to when '+=' fetches the value of ResultsTextBox, you  
        // would not see the global side effect of ExampleMethodAsync setting the text.  
        ResultsTextBox.Text += String.Format("Length: {0:N0}\n", length);
    }
    catch (Exception)
    {
        // Process the exception if one occurs.  
    }
}

public async Task<int> ExampleMethodAsync()
{
    var httpClient = new HttpClient();
    int exampleInt = (await httpClient.GetStringAsync("http://msdn.microsoft.com")).Length;
    ResultsTextBox.Text += "Preparing to finish ExampleMethodAsync.\n";
    // After the following return statement, any method that's awaiting  
    // ExampleMethodAsync (in this case, StartButton_Click) can get the   
    // integer result.  
    return exampleInt;
}
// The example displays the following output:  
// Preparing to finish ExampleMethodAsync.  
// Length: 53292  

重要

タスクの詳細、およびタスクを待機している間に実行されるコードの詳細については、「Async および Await を使用した非同期プログラミング」をご覧ください。For more information about tasks and the code that executes while waiting for a task, see Asynchronous Programming with async and await. 同様の要素を使用する WPF 例の完全版については、「チュートリアル: Async と Await を使用した Web へのアクセス」をご覧ください。For a full WPF example that uses similar elements, see Walkthrough: Accessing the Web by Using Async and Await.

戻り値の型Return Types

非同期メソッドの戻り値の型を次に示します。An async method can have the following return types:

  • Task
  • Task<TResult>
  • void: イベント ハンドラーに対してのみ使用します。void, which should only be used for event handlers.
  • C# 7.0 以降、アクセス可能な GetAwaiter を持つ任意の型です。Starting with C# 7.0, any type that has an accessible GetAwaiter method. System.Threading.Tasks.ValueTask<TResult> 型はこの実装例で、The System.Threading.Tasks.ValueTask<TResult> type is one such implementation. NuGet パッケージ System.Threading.Tasks.Extensions を追加することで使用できます。It is available by adding the NuGet package System.Threading.Tasks.Extensions.

非同期メソッドでは inrefout パラメーターを宣言できません。また、参照戻り値を指定することもできません。ただし、これらのパラメーターを持つメソッドを呼び出すことはできます。The async method can't declare any in, ref or out parameters, nor can it have a reference return value, but it can call methods that have such parameters.

メソッドの return ステートメントで TResult 型のオペランドを指定している場合、非同期メソッドの戻り値の型として Task<TResult> を指定します。You specify Task<TResult> as the return type of an async method if the return statement of the method specifies an operand of type TResult. メソッドの完了時に意味のある値を返さない場合は、Task を使用します。You use Task if no meaningful value is returned when the method is completed. これにより、メソッドの呼び出しでは Task が返されますが、Task の完了時に、await を待機している Task 式はすべて、void に評価されます。That is, a call to the method returns a Task, but when the Task is completed, any await expression that's awaiting the Task evaluates to void.

戻り値の型 void は主として、戻り値の型が必要なイベント ハンドラーの定義に使用されます。You use the void return type primarily to define event handlers, which require that return type. void を返す非同期メソッドの呼び出し元は、このメソッドを待機できず、このメソッドがスローする例外をキャッチできません。The caller of a void-returning async method can't await it and can't catch exceptions that the method throws.

C# 7.0 以降、GetAwaiter メソッドを持つ別の型 (通常は値の型) を返して、コードのパフォーマンスが重要なセクションでメモリ割り当てを最小限に抑えます。Starting with C# 7.0, you return another type, typically a value type, that has a GetAwaiter method to miminize memory allocations in performance-critical sections of code.

使用例を含む詳細については、「非同期の戻り値の型」をご覧ください。For more information and examples, see Async Return Types.

参照See Also

AsyncStateMachineAttribute
awaitawait
チュートリアル: Async と Await を使用した Web へのアクセスWalkthrough: Accessing the Web by Using Async and Await
Async および Await を使用した非同期プログラミングAsynchronous Programming with async and await