Bagikan melalui

asinkron (referensi C#)

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

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

Referensi bahasa C# mendokumentasikan versi bahasa C# yang paling baru dirilis. Ini juga berisi dokumentasi awal untuk fitur dalam pratinjau publik untuk rilis bahasa yang akan datang.

Dokumentasi mengidentifikasi fitur apa pun yang pertama kali diperkenalkan dalam tiga versi terakhir bahasa atau dalam pratinjau publik saat ini.

Petunjuk / Saran

Untuk menemukan kapan fitur pertama kali diperkenalkan di C#, lihat artikel tentang riwayat versi bahasa C#.

Jika Anda baru menggunakan pemrograman asinkron atau tidak memahami bagaimana metode asinkron menggunakan operator untuk melakukan pekerjaan yang berpotensi berjalan lama tanpa memblokir utas await pemanggil, baca pengenalan dalam pemrograman Asinkron dengan asinkron dan tunggu. 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 . Pada titik itu, metode ditangguhkan sampai 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 async kuncinya kontekstual. Ini adalah kata kunci hanya ketika memodifikasi metode, ekspresi lambda, atau metode anonim. Dalam semua konteks lainnya, pengkompilasi menafsirkannya sebagai pengidentifikasi.

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 using direktif 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#).

Tipe pengembalian

Metode async dapat memiliki jenis pengembalian berikut:

  • Task
  • Task<TResult>
  • void. Umumnya, hindari menggunakan async void metode untuk kode selain penanganan aktivitas karena penelepon tidak await dapat 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 System.Threading.Tasks.ExtensionsNuGet .

Metode asinkron tidak dapat mendeklarasikan parameter , ref, ref readonly, atau out apa punin, juga tidak dapat memiliki nilai pengembalian referensi. Namun, ini dapat memanggil metode yang memiliki parameter seperti itu.

Tentukan Task<TResult> sebagai jenis pengembalian metode asinkron jika pernyataan pengembalian metode menentukan operand jenis TResult. Gunakan Task jika metode tidak mengembalikan nilai yang bermakna saat selesai. Artinya, panggilan ke metode mengembalikan Task, tetapi ketika Task selesai, ekspresi await apa pun yang menunggu Task evaluasi ke void. void Gunakan jenis pengembalian 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. 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

  • Last updated on