async (Referensi C#)

  • Artikel

Gunakan pengubah async untuk menentukan bahwa metode, ekspresi lambda, atau metode anonim asinkron. Jika Anda menggunakan pengubah ini pada metode atau ekspresi, itu disebut sebagai metode asinkron. Contoh berikut mendefinisikan metode asinkron bernama ExampleMethodAsync:

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

Jika Anda baru mengenal pemrograman asinkron atau tidak mengerti bagaimana metode async menggunakan await operator untuk melakukan pekerjaan yang berpotensi berjalan lama tanpa memblokir utas pemanggil, baca pengantar dalam pemrograman asinkron dengan async dan await. Kode berikut ditemukan di dalam metode asinkron dan memanggil metode HttpClient.GetStringAsync:

string contents = await httpClient.GetStringAsync(requestUrl);

Metode asinkron berjalan secara sinkron sampai mencapai ekspresi pertamanya await, di mana metode ditangguhkan hingga tugas yang ditunggu selesai. Sementara itu, kontrol kembali ke pemanggil metode, seperti yang ditunjukkan oleh contoh di bagian berikutnya.

Jika metode yang dimodifikasi kata kunci async tidak berisi ekspresi atau pernyataan await, metode akan dijalankan secara sinkron. Peringatan kompiler menunjukkan Anda segera ke metode asinkron apa pun yang tidak memuat await karena situasi tersebut mungkin menunjukkan kesalahan. Lihat Peringatan Kompiler (level 1) CS4014.

Kata kunci async bersifat kontekstual karena kata kunci hanya ketika memodifikasi metode, ekspresi lambda, atau metode anonim. Dalam semua konteks lain, itu ditafsirkan sebagai pengenal.

Contoh

Contoh berikut menunjukkan struktur dan alur kontrol antara penanganan aktivitas asinkron, StartButton_Click, dan metode asinkron, ExampleMethodAsync. Hasil dari metode async adalah jumlah karakter halaman web. Kode ini cocok untuk aplikasi Windows Presentation Foundation (WPF) atau aplikasi Windows Store yang Anda buat di Visual Studio; lihat komentar kode untuk menyiapkan aplikasi.

Anda dapat menjalankan kode ini di Visual Studio sebagai aplikasi Windows Presentation Foundation (WPF) atau aplikasi Windows Store. Anda memerlukan kontrol Tombol bernama StartButton dan kontrol Kotak Teks bernama ResultsTextBox. Ingatlah untuk mengatur nama dan penanganan sehingga Anda memiliki sesuatu seperti ini:

<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"/>

Untuk menjalankan kode sebagai aplikasi WPF:

  • Tempelkan kode ini ke kelas MainWindow di MainWindow.xaml.cs.
  • Tambahkan referensi ke System.Net.Http.
  • Tambahkan direktif using untuk System.Net.Http.

Untuk menjalankan kode sebagai aplikasi Windows Store:

  • Tempelkan kode ini ke kelas MainPage di MainWindow.xaml.cs.
  • Tambahkan menggunakan arahan untuk System.Net.Http dan 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

Penting

Untuk informasi selengkapnya tentang tugas dan kode yang dijalankan saat menunggu tugas, lihat Pemrograman asinkron dengan async dan await. Untuk contoh konsol lengkap yang menggunakan elemen serupa, lihat Memproses tugas asinkron saat selesai (C#).

Jenis Kembalian

Metode async dapat memiliki jenis pengembalian berikut:

  • Task
  • Task<TResult>
  • void. metode async void umumnya tidak disarankan untuk kode selain penanganan aktivitas karena pemanggil tidak dapat await menggunakan metode tersebut dan harus menerapkan mekanisme yang berbeda untuk melaporkan penyelesaian yang berhasil atau kondisi kesalahan.
  • Jenis apa pun yang memiliki metode yang dapat diakses GetAwaiter . Jenis System.Threading.Tasks.ValueTask<TResult> adalah salah satu implementasi seperti itu. Ini tersedia dengan menambahkan paket NuGet System.Threading.Tasks.Extensions.

Metode asinkron tidak dapat mendeklarasikan parameter in, ref, atau out, juga tidak dapat memiliki nilai pengembalian referensi, tetapi dapat memanggil metode yang memiliki parameter tersebut.

Anda menentukan Task<TResult> untuk jenis pengembalian metode asinkron jika pernyataan return metode memiliki operan jenis TResult. Anda menggunakan Task jika tidak ada nilai yang bermakna dikembalikan ketika metode selesai. Artinya, panggilan ke metode mengembalikan Task, tetapi ketika Task selesai, ekspresi await apa pun yang menunggu Task evaluasi ke void.

Anda menggunakan jenis pengembalian void terutama untuk menentukan penanganan aktivitas, yang memerlukan jenis pengembalian tersebut. Pemanggil void-pengembalian metode async tidak dapat menunggunya dan tidak dapat menangkap pengecualian yang dilemparkan metode.

Anda mengembalikan jenis lain, biasanya jenis nilai, yang memiliki GetAwaiter metode untuk meminimalkan alokasi memori di bagian kode kritis performa.

Untuk informasi dan contoh selengkapnya, lihat Jenis Pengembalian Asinkron.

Lihat juga