非同步程式設計案例

如果您有任何 I/O 繫結需求 (例如，從網路要求資料、存取資料庫或讀取和寫入檔案系統)，則可以利用非同步程式設計。 您也可能會有 CPU 繫結程式碼，例如執行耗費資源的計算，這也是不錯的非同步程式碼撰寫案例。

C# 具有語言層級非同步程式設計模型，可輕鬆撰寫非同步程式碼，而不需要竄改回呼或符合支援非同步的程式庫。 它會遵循稱為工作式非同步模式 (TAP) 的模式。

非同步模型的概觀

非同步程式設計的核心是建立非同步作業模型的 Task 和 Task<T> 物件。 它們是受 async 和 await 關鍵字所支援。 在大部分情況下，模型都相當簡單︰

• 針對 I/O 繫結程式碼，您可以等待在 async 方法內傳回 Task 或 Task<T> 的作業。
• 針對 CPU 繫結程式碼，您可以等待使用 Task.Run 方法在背景執行緒上啟動的作業。

await 關鍵字就是顯現魔力的地方。 它會將控制交給執行 await 的方法呼叫端，最後讓 UI 有回應或服務有彈性。 雖然有方法可以處理 async 與 await 以外的非同步程式碼，但此文章著重在語言層級建構。

注意

在下列範例中， System.Net.Http.HttpClient 類別用於從 Web 服務中下載某些資料。 這些範例中使用的 s_httpClient 物件是 Program 類別的靜態欄位 (請檢查完整範例)：

private static readonly HttpClient s_httpClient = new();

I/O 繫結範例︰從 Web 服務下載資料

您可能需要在按下按鈕時，從 Web 服務下載一些資料，但不想要封鎖 UI 執行緒。 只要使用下列方式，即可完成這個目的：

s_downloadButton.Clicked += async (o, e) =>
{
    // This line will yield control to the UI as the request
    // from the web service is happening.
    //
    // The UI thread is now free to perform other work.
    var stringData = await s_httpClient.GetStringAsync(URL);
    DoSomethingWithData(stringData);
};

程式碼會表達意圖 (非同步下載資料)，而不陷入與 Task 物件的互動。

CPU 繫結範例：對遊戲執行計算

假設您正在撰寫行動遊戲，而按下按鈕可能會損壞畫面上的許多敵人。 執行損壞計算可能十分耗費資源，而且在 UI 執行緒上這麼做會讓遊戲似乎在執行計算時暫停！

處理這種情形的最佳方式是啟動背景執行緒，以使用 Task.Run 執行工作並使用 await 等待其結果。 這可讓 UI 順暢地完成工作。

static DamageResult CalculateDamageDone()
{
    return new DamageResult()
    {
        // Code omitted:
        //
        // Does an expensive calculation and returns
        // the result of that calculation.
    };
}

s_calculateButton.Clicked += async (o, e) =>
{
    // This line will yield control to the UI while CalculateDamageDone()
    // performs its work. The UI thread is free to perform other work.
    var damageResult = await Task.Run(() => CalculateDamageDone());
    DisplayDamage(damageResult);
};

此程式碼可清楚地表達按鈕 click 事件的意圖、不需要手動管理背景執行緒，而且以非封鎖方式進行。

背後作業

在 C# 端，編譯器會將程式碼轉換為狀態機器，可追蹤在達到 await 時暫止執行，並在完成背景工作後繼續執行等狀態。

基於理論上的需要，這是非同步的承諾模型的實作。

要了解的重要部分

• 非同步程式碼可以用於 I/O 繫結和 CPU 繫結程式碼，但每個案例都不同。
• 非同步程式碼會使用 Task<T> 和 Task，這是用來在背景中完成建立工作模型的建構。
• async 關鍵字會將方法轉換為非同步方法，讓您可以在其主體中使用 await 關鍵字。
• 套用 await 關鍵字時，除非等候的工作完成，否則會暫止呼叫的方法，並將控制權返回其呼叫端。
• await 只能在非同步方法內使用。

辨識 CPU 繫結和 I/O 繫結工作

此手冊的前兩個範例示範如何使用 async 與 await 進行 I/O 繫結與 CPU 繫結工作。 這是您識別所需執行的工作是 I/O 繫結還是 CPU 繫結的關鍵，因為其會大幅影響程式碼的效能，而且可能會導致誤用特定建構。

以下是您應該在撰寫任何程式碼之前提問的兩個問題︰

1. 程式碼是否要「等候」什麼項目，例如資料庫中的資料？

   如果您的答案為「是」，則工作是 I/O 繫結。

2. 您的程式碼會執行耗費資源的計算嗎？

   如果您的答案為「是」，則工作是 CPU 繫結。

如果您的工作是 [I/O 繫結]，請使用沒有 Task.Run 的 async 和 await。 您「不應該」使用 Task Parallel Library。

如果您的工作是 [CPU 繫結]，而且您關心回應性，請使用 async 與 await，但在另一個執行緒上使用 Task.Run 繁衍工作。 如果工作適用於並行與平行處理原則，也可以考慮使用工作平行程式庫。

此外，您應該一律測量程式碼的執行。 例如，您可能會發現，在進行多執行緒處理時，與內容切換的負擔相較之下，CPU 繫結工作較不耗費資源。 每個選項都有其取捨，您應該挑選適用於您情況的正確取捨。

更多範例

下列範例示範可使用 C# 撰寫非同步程式碼的各種方式。 它們會涵蓋數個您可能會遇到的不同案例。

從網路擷取資料

此程式碼片段會從指定的 URL 下載 HTML，並計算字串 ".NET" 在 HTML 中的出現次數。 其會使用 ASP.NET 來定義執行此工作並傳回數字的 Web API 控制器方法。

注意

如果您打算在生產程式碼中執行 HTML 剖析，請不要使用規則運算式。 請改用剖析程式庫。

[HttpGet, Route("DotNetCount")]
static public async Task<int> GetDotNetCount(string URL)
{
    // Suspends GetDotNetCount() to allow the caller (the web server)
    // to accept another request, rather than blocking on this one.
    var html = await s_httpClient.GetStringAsync(URL);
    return Regex.Matches(html, @"\.NET").Count;
}

以下是針對通用 Windows 應用程式撰寫的相同案例，而通用 Windows 應用程式會在按下按鈕時執行相同工作︰

private readonly HttpClient _httpClient = new HttpClient();

private async void OnSeeTheDotNetsButtonClick(object sender, RoutedEventArgs e)
{
    // Capture the task handle here so we can await the background task later.
    var getDotNetFoundationHtmlTask = _httpClient.GetStringAsync("https://dotnetfoundation.org");

    // Any other work on the UI thread can be done here, such as enabling a Progress Bar.
    // This is important to do here, before the "await" call, so that the user
    // sees the progress bar before execution of this method is yielded.
    NetworkProgressBar.IsEnabled = true;
    NetworkProgressBar.Visibility = Visibility.Visible;

    // The await operator suspends OnSeeTheDotNetsButtonClick(), returning control to its caller.
    // This is what allows the app to be responsive and not block the UI thread.
    var html = await getDotNetFoundationHtmlTask;
    int count = Regex.Matches(html, @"\.NET").Count;

    DotNetCountLabel.Text = $"Number of .NETs on dotnetfoundation.org: {count}";

    NetworkProgressBar.IsEnabled = false;
    NetworkProgressBar.Visibility = Visibility.Collapsed;
}

等候多個工作完成

您可能會發現必須同時擷取多個資料片段。 Task API 包含兩種方法︰Task.WhenAll 與 Task.WhenAny，可讓您撰寫對多個背景作業執行非封鎖等候的非同步程式碼。

這個範例示範如何捕捉一組 userId 的 User 資料。

private static async Task<User> GetUserAsync(int userId)
{
    // Code omitted:
    //
    // Given a user Id {userId}, retrieves a User object corresponding
    // to the entry in the database with {userId} as its Id.

    return await Task.FromResult(new User() { id = userId });
}

private static async Task<IEnumerable<User>> GetUsersAsync(IEnumerable<int> userIds)
{
    var getUserTasks = new List<Task<User>>();
    foreach (int userId in userIds)
    {
        getUserTasks.Add(GetUserAsync(userId));
    }

    return await Task.WhenAll(getUserTasks);
}

以下是使用 LINQ，以更簡潔的方式撰寫此程式碼的另一種方式：

private static async Task<User[]> GetUsersAsyncByLINQ(IEnumerable<int> userIds)
{
    var getUserTasks = userIds.Select(id => GetUserAsync(id)).ToArray();
    return await Task.WhenAll(getUserTasks);
}

雖然程式碼較少，但是混合使用 LINQ 與非同步程式碼時請小心。 因為 LINQ 使用延後 (延遲) 執行，所以除非使用 .ToList() 或 .ToArray() 呼叫強制逐一查看產生的序列，否則不會像在 foreach 迴圈中一樣立即進行非同步呼叫。 上述範例會使用 Enumerable.ToArray 來積極執行查詢，並將結果儲存在陣列中。 這可強制程式碼 id => GetUserAsync(id) 執行並啟動工作。

重要資訊和建議

使用非同步程式設計時需要牢記一些細節，以避免發生非預期的行為。

• async 方法需要其主體中有 await 關鍵字，否則它們將永遠不會產生！

  這是需要記住的重要事項。 如果 await 未用於 async 方法的主體，C# 編譯器將會產生警告，但程式碼的編譯和執行就像一般方法一樣。 這非常沒有效率，因為 C# 編譯器針對非同步方法所產生的狀態機器不會完成任何作業。

• 新增 “Async” 作為您撰寫之每個非同步方法名稱的尾碼。

  這是 .NET 中所使用的慣例，可更輕鬆地區分同步與非同步方法。 系統不一定會套用程式碼未明確呼叫的特定方法 (例如事件處理常式或 Web 控制器方法)。 由於您的程式碼未明確呼叫這些方法，因此明確命名並不重要。

• async void 應該只用於事件處理常式。

  因為事件沒有傳回型別 (因此無法利用 Task 和 Task<T>)，所以 async void 是允許非同步事件處理常式運作的唯一方式。 async void 的任何其他使用都未遵循 TAP 模型，而且不容易使用，例如：

  • async void 方法中所擲回的例外狀況無法在該方法外部進行攔截。
  • async void 方法難以測試。
  • async void 方法在呼叫者未預期其為非同步的情況下，可能會造成不好的副作用。

• 在 LINQ 運算式中使用非同步 Lambda 時，請小心處理

  LINQ 中的 Lambda 運算式會使用延後執行，這表示程式碼可以在未預期其執行時結束執行。 如果未正確撰寫，則將封鎖工作導入這個作業很容易會造成死結。 此外，這類非同步程式碼的巢狀結構也更難分析程式碼的執行。 非同步和 LINQ 功能強大，但應該盡可能小心且清楚地一起使用。

• 以非封鎖方式撰寫等候工作的程式碼

  封鎖目前執行緒作為等候 Task 完成的方式可能會造成死結和封鎖的內容執行緒，而且可能需要更複雜的錯誤處理。 下表提供如何處理以非封鎖方式等候工作的指引：

  使用這個項目...	而不是這個項目...	執行時機...
  await	Task.Wait 或 Task.Result	擷取背景工作的結果
  await Task.WhenAny	Task.WaitAny	等候任何工作完成
  await Task.WhenAll	Task.WaitAll	等候所有工作完成
  await Task.Delay	Thread.Sleep	等候一段時間

• 請考慮盡可能使用 ValueTask

  從非同步方法傳回 Task 物件可能會造成在特定路徑的效能瓶頸。 Task 是參考型別，因此使用它表示要配置物件。 當使用 async 修飾詞宣告的方法傳回快取的結果，或是以同步方式完成時，額外配置可能會在效能關鍵的程式碼區段中變成一個重要的時間成本。 如果這些配置發生在緊密迴圈中，它可能會變得成本很高。 如需詳細資訊，請參閱通用的非同步傳回型別。

• 考慮使用 ConfigureAwait(false)

  常見問題是「什麼時候應該使用 Task.ConfigureAwait(Boolean) 方法？」。 此方法可讓 Task 執行個體設定其 awaiter。 這是重要的考量點，而且設定不正確可能會造成效能影響，甚至死結。 如需有關 ConfigureAwait 的詳細資訊，請參閱 ConfigureAwait 常見問題集 (英文)。

• 撰寫較不具狀態的程式碼

  請不要依賴全域物件的狀態或特定方法的執行。 相反地，請只取決於方法的傳回值。 為什麼？

  • 程式碼會比較容易理解。
  • 程式碼會比較容易測試。
  • 混合使用非同步與同步程式碼則相當簡單。
  • 一般可以避免追蹤條件。
  • 根據傳回值，讓非同步程式碼的協調更為簡單。
  • (紅利) 它可實際與相依性插入良好搭配。

建議的目標是在程式碼中達到完全或幾乎完全的 Referential Transparency (參考透明度)。 這樣做將會導致可預測、可測試和可維護的程式碼基底。

完整範例

下列程式碼是範例 Program.cs 檔案的完整文字。

using System.Text.RegularExpressions;
using System.Windows;
using Microsoft.AspNetCore.Mvc;

class Button
{
    public Func<object, object, Task>? Clicked
    {
        get;
        internal set;
    }
}

class DamageResult
{
    public int Damage
    {
        get { return 0; }
    }
}

class User
{
    public bool isEnabled
    {
        get;
        set;
    }

    public int id
    {
        get;
        set;
    }
}

public class Program
{
    private static readonly Button s_downloadButton = new();
    private static readonly Button s_calculateButton = new();

    private static readonly HttpClient s_httpClient = new();

    private static readonly IEnumerable<string> s_urlList = new string[]
    {
            "https://learn.microsoft.com",
            "https://learn.microsoft.com/aspnet/core",
            "https://learn.microsoft.com/azure",
            "https://learn.microsoft.com/azure/devops",
            "https://learn.microsoft.com/dotnet",
            "https://learn.microsoft.com/dotnet/desktop/wpf/get-started/create-app-visual-studio",
            "https://learn.microsoft.com/education",
            "https://learn.microsoft.com/shows/net-core-101/what-is-net",
            "https://learn.microsoft.com/enterprise-mobility-security",
            "https://learn.microsoft.com/gaming",
            "https://learn.microsoft.com/graph",
            "https://learn.microsoft.com/microsoft-365",
            "https://learn.microsoft.com/office",
            "https://learn.microsoft.com/powershell",
            "https://learn.microsoft.com/sql",
            "https://learn.microsoft.com/surface",
            "https://dotnetfoundation.org",
            "https://learn.microsoft.com/visualstudio",
            "https://learn.microsoft.com/windows",
            "https://learn.microsoft.com/maui"
    };

    private static void Calculate()
    {
        // <PerformGameCalculation>
        static DamageResult CalculateDamageDone()
        {
            return new DamageResult()
            {
                // Code omitted:
                //
                // Does an expensive calculation and returns
                // the result of that calculation.
            };
        }

        s_calculateButton.Clicked += async (o, e) =>
        {
            // This line will yield control to the UI while CalculateDamageDone()
            // performs its work. The UI thread is free to perform other work.
            var damageResult = await Task.Run(() => CalculateDamageDone());
            DisplayDamage(damageResult);
        };
        // </PerformGameCalculation>
    }

    private static void DisplayDamage(DamageResult damage)
    {
        Console.WriteLine(damage.Damage);
    }

    private static void Download(string URL)
    {
        // <UnblockingDownload>
        s_downloadButton.Clicked += async (o, e) =>
        {
            // This line will yield control to the UI as the request
            // from the web service is happening.
            //
            // The UI thread is now free to perform other work.
            var stringData = await s_httpClient.GetStringAsync(URL);
            DoSomethingWithData(stringData);
        };
        // </UnblockingDownload>
    }

    private static void DoSomethingWithData(object stringData)
    {
        Console.WriteLine("Displaying data: ", stringData);
    }

    // <GetUsersForDataset>
    private static async Task<User> GetUserAsync(int userId)
    {
        // Code omitted:
        //
        // Given a user Id {userId}, retrieves a User object corresponding
        // to the entry in the database with {userId} as its Id.

        return await Task.FromResult(new User() { id = userId });
    }

    private static async Task<IEnumerable<User>> GetUsersAsync(IEnumerable<int> userIds)
    {
        var getUserTasks = new List<Task<User>>();
        foreach (int userId in userIds)
        {
            getUserTasks.Add(GetUserAsync(userId));
        }

        return await Task.WhenAll(getUserTasks);
    }
    // </GetUsersForDataset>

    // <GetUsersForDatasetByLINQ>
    private static async Task<User[]> GetUsersAsyncByLINQ(IEnumerable<int> userIds)
    {
        var getUserTasks = userIds.Select(id => GetUserAsync(id)).ToArray();
        return await Task.WhenAll(getUserTasks);
    }
    // </GetUsersForDatasetByLINQ>

    // <ExtractDataFromNetwork>
    [HttpGet, Route("DotNetCount")]
    static public async Task<int> GetDotNetCount(string URL)
    {
        // Suspends GetDotNetCount() to allow the caller (the web server)
        // to accept another request, rather than blocking on this one.
        var html = await s_httpClient.GetStringAsync(URL);
        return Regex.Matches(html, @"\.NET").Count;
    }
    // </ExtractDataFromNetwork>

    static async Task Main()
    {
        Console.WriteLine("Application started.");

        Console.WriteLine("Counting '.NET' phrase in websites...");
        int total = 0;
        foreach (string url in s_urlList)
        {
            var result = await GetDotNetCount(url);
            Console.WriteLine($"{url}: {result}");
            total += result;
        }
        Console.WriteLine("Total: " + total);

        Console.WriteLine("Retrieving User objects with list of IDs...");
        IEnumerable<int> ids = new int[] { 1, 2, 3, 4, 5, 6, 7, 8, 9, 0 };
        var users = await GetUsersAsync(ids);
        foreach (User? user in users)
        {
            Console.WriteLine($"{user.id}: isEnabled={user.isEnabled}");
        }

        Console.WriteLine("Application ending.");
    }
}

// Example output:
//
// Application started.
// Counting '.NET' phrase in websites...
// https://learn.microsoft.com: 0
// https://learn.microsoft.com/aspnet/core: 57
// https://learn.microsoft.com/azure: 1
// https://learn.microsoft.com/azure/devops: 2
// https://learn.microsoft.com/dotnet: 83
// https://learn.microsoft.com/dotnet/desktop/wpf/get-started/create-app-visual-studio: 31
// https://learn.microsoft.com/education: 0
// https://learn.microsoft.com/shows/net-core-101/what-is-net: 42
// https://learn.microsoft.com/enterprise-mobility-security: 0
// https://learn.microsoft.com/gaming: 0
// https://learn.microsoft.com/graph: 0
// https://learn.microsoft.com/microsoft-365: 0
// https://learn.microsoft.com/office: 0
// https://learn.microsoft.com/powershell: 0
// https://learn.microsoft.com/sql: 0
// https://learn.microsoft.com/surface: 0
// https://dotnetfoundation.org: 16
// https://learn.microsoft.com/visualstudio: 0
// https://learn.microsoft.com/windows: 0
// https://learn.microsoft.com/maui: 6
// Total: 238
// Retrieving User objects with list of IDs...
// 1: isEnabled= False
// 2: isEnabled= False
// 3: isEnabled= False
// 4: isEnabled= False
// 5: isEnabled= False
// 6: isEnabled= False
// 7: isEnabled= False
// 8: isEnabled= False
// 9: isEnabled= False
// 0: isEnabled= False
// Application ending.

其他資源

• 非同步工作程式設計模型 (C#)。