使用 C# 建立第一個長期函式

發行項
04/07/2024

Durable Functions 是 Azure Functions 的延伸模組，可讓您在無伺服器環境中撰寫具狀態函式。此擴充功能會為您管理狀態、設定檢查點和重新啟動。

在本文中，您將瞭解如何使用 Visual Studio Code 在本機建立及測試「hello world」耐久函式。此函式會將呼叫協調並鏈結至其他函式。然後，您可以將函式程式代碼發佈至 Azure。這些工具是 Visual Studio Code Azure Functions 延伸模組的一部分。

Visual Studio Code 視窗與耐久函式的螢幕快照。

必要條件

完成本教學課程：

安裝 Visual Studio Code。
安裝下列 Visual Studio Code 延伸模組：
- Azure Functions
- C#
請確定您有最新版的 Azure Functions Core Tools。
Durable Functions 需要 Azure 儲存體帳戶。您需要訂閱 Azure。
請確定您已安裝 3.1 版或更新版本的 .NET Core SDK 。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

建立本機專案

在這一節中，您會使用 Visual Studio Code 來建立本機 Azure Functions 專案。

在 Visual Studio Code 中，按 F1 （或 Ctrl/Cmd+Shift+P）以開啟命令選擇區。在命令選擇區中，搜尋並選取 Azure Functions: Create New Project...。
為您的專案選擇空白資料夾位置，然後選擇 [選取]。

依照提示操作並提供下列資訊：

提示	值	Description
為您的函式應用程式專案選取語言	C#	建立本機 C# Functions 專案。
選取版本	Azure Functions v4	您只會在尚未安裝 Core Tools 時看到此選項。在此情況下，Core Tools 會在您第一次執行應用程式時安裝。
為您專案的第一個函式選取範本	暫時跳過
選取您要如何開啟專案	在目前視窗中開啟	重新開啟您所選取資料夾中的 Visual Studio Code。

Visual Studio Code 會視需要安裝 Azure Functions Core Tools。其也會在資料夾中建立函式應用程式專案。此專案包含 host.json 和 local.settings.json 組態檔。

將函式新增至應用程式

下列步驟會使用範本在專案中建立耐久函式程序代碼。

在命令選擇區中，搜尋並選取 Azure Functions: Create Function...。

依照提示操作並提供下列資訊：

提示	值	Description
為您的函式選取範本	DurableFunctionsOrchestration	建立 Durable Functions 協調流程
提供函式名稱	HelloOrchestration	在其中建立函式的類別名稱
提供命名空間	Company.Function	所產生類別的命名空間

當 Visual Studio Code 提示您選取記憶體帳戶時，請選擇 [ 選取記憶體帳戶]。請遵循提示，並提供下列資訊，在 Azure 中建立新的記憶體帳戶：

提示	值	Description
選取訂閱	您的訂用帳戶名稱	選取您的 Azure 訂用帳戶
選取儲存體帳戶	建立新的儲存體帳戶
輸入新儲存體帳戶的名稱	唯一名稱	要建立的儲存體帳戶名稱
選取資源群組	唯一名稱	要建立的資源群組名稱
選取位置	region	選取鄰近您的區域

包含新函式的類別會新增至專案。 Visual Studio Code 也會將記憶體帳戶連接字串新增至 local.settings.json，並將 NuGet 套件的Microsoft.Azure.WebJobs.Extensions.DurableTask參考新增至 .csproj 項目檔。

開啟新的 HelloOrchestration.cs 檔案以檢視內容。這個耐久函式是具有下列方法的簡單函式鏈結範例：

方法	函數名稱	描述
`RunOrchestrator`	`HelloOrchestration`	管理永久性協調流程。在此情況下，協調流程會啟動、建立清單，並將三個函式呼叫的結果新增至清單。當三個函式呼叫完成時，它會傳回清單。
`SayHello`	`HelloOrchestration_Hello`	函式會傳回 hello。這是包含正在協調之商業規則的函式。
`HttpStart`	`HelloOrchestration_HttpStart`	HTTP 觸發的函式，會啟動協調流程的實例，並傳回檢查狀態回應。

既然您已建立函式專案和耐久函式，您可以在本機計算機上進行測試。

在本機測試函式

Azure Functions Core Tools 可讓您在本機開發電腦上執行 Azure Functions 專案。第一次從 Visual Studio Code 啟動函式時，系統會提示您安裝這些工具。

若要測試您的函式，請在活動函式程式代碼中 SayHello 設定斷點，然後按 F5 以啟動函式應用程式專案。 Core Tools 的輸出會顯示在 [終端機] 面板中。

注意

如需偵錯的詳細資訊，請參閱 Durable Functions 診斷。
在終端機面板中，複製 HTTP 觸發函式的 URL 端點。
使用 Postman 或 cURL 之類的工具，然後將 HTTP POST 要求傳送至 URL 端點。

回應是 HTTP 函式的初始結果，讓我們知道長期協調流程已成功啟動。這還不是協調流程的最終結果。回應包含一些實用的 URL。讓現在我們查詢協調流程的狀態。

複製的 URL 值 statusQueryGetUri，將其貼到瀏覽器的網址列中，然後執行要求。或者，您也可以繼續使用 Postman 發出 GET 要求。

此要求會查詢協調流程執行個體的狀態。您必須取得最終回應，這會顯示實例已完成，並包含耐久函式的輸出或結果。如下所示：

{
    "name": "HelloOrchestration",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

若要停止偵錯，請按 Visual Studio Code 中的 Shift + F5 。

確認函式在本機電腦上正確執行之後，就可以將專案發佈到 Azure。

您必須先登入 Azure，才能建立 Azure 資源或發布應用程式。

如果您尚未登入，請選擇 [活動] 列中的 Azure 圖示。然後在 [資源] 區域中，選擇 [登入 Azure...]。

如果您已登入，而且可以看到現有的訂閱，請移至下一節。如果您尚未擁有 Azure 帳戶，請選擇 [建立 Azure 帳戶...]。學生可以選擇 [建立 Azure 學生版帳戶...]。
當在瀏覽器中收到提示時，請使用您的 Azure 帳戶認證選擇 Azure 帳戶並登入。如果您建立新的帳戶，可以在帳戶建立之後登入。
成功登入之後，即可關閉新的瀏覽器視窗。屬於您 Azure 帳戶的訂用帳戶會顯示在提要欄位中。

在 Azure 中建立函式應用程式

在此區段中，您會在 Azure 訂用帳戶中建立函式應用程式和相關的資源。

選擇 [活動] 列中的 Azure 圖示。然後在 [資源] 區域中，選取 + 圖示並選擇 [在 Azure 中建立函數應用程式] 選項。

提示中會提供下列資訊：

提示	選取項目
選取訂用帳戶	選擇要使用的訂用帳戶。當您只有一個訂閱顯示在 [資源] 底下時，就不會看到此提示。
輸入函數應用程式的全域唯一名稱	輸入在 URL 路徑中有效的名稱。您鍵入的名稱會經過驗證，確定其在 Azure Functions 中是唯一。
選取執行階段堆疊	選擇您在本機上執行的語言版本。
選取新資源的位置	若要獲得較佳的效能，請選擇您附近的區域。

該延伸模組會在 [Azure: 活動記錄] 面板顯示正在 Azure 建立的個別資源狀態。

建立 Azure 資源的記錄

建立完成時，您的訂閱中會建立下列 Azure 資源。資源會根據您的函數應用程式名稱命名：
- 資源群組，這是相關資源的邏輯容器。
- 標準 Azure 儲存體帳戶，其可維護專案的狀態和其他資訊。
- 函數應用程式，其提供執行函式程式碼的環境。函數應用程式可讓您將函式以邏輯單位分組，方便您在相同的主控方案中管理、部署及共用資源。
- App Service 方案，其定義函數應用程式的基礎主機。
- 連線至函數應用程式的 Application Insights 執行個體，可追蹤應用程式中函式的使用量。
建立函式應用程式並套用部署套件之後，即會顯示通知。

提示

根據預設，系統會依照您提供的函數應用程式名稱建立函數應用程式所需的 Azure 資源，並且預設會建立在與函數應用程式相同的新資源群組中。如果您想自訂這些資源的名稱或重複使用現有的資源，必須改為使用進階建立選項發佈專案。

將專案部署至 Azure

重要

部署至現有的函數應用程式一律會覆寫該應用程式在 Azure 中的內容。

在 Azure 活動的 [資源] 區域中，找出您剛才建立的函數應用程式資源，以滑鼠右鍵按一下該資源，然後選取 [部署至函數應用程式...]。
當系統提示您覆寫先前的部署時，請選取 [部署]，將函式程式碼部署至新的函數應用程式資源。
部署完成時，選取 [檢視輸出] 即可檢視建立和部署結果，包括您所建立的 Azure 資源。如果您錯過通知，請選取右下角的鈴鐺圖示，以再次查看。

在 Azure 中測試您的函式

從 [輸出] 面板中複製 HTTP 觸發程序的 URL。呼叫 HTTP 觸發函式的 URL 必須具有下列格式：

https://<functionappname>.azurewebsites.net/api/HelloOrchestration_HttpStart
將 HTTP 要求的新 URL 貼到瀏覽器的網址列。使用已發佈的應用程式時，您必須取得與之前相同的狀態回應。

下一步

您已使用 Visual Studio Code 來建立及發布 C# 耐久函式應用程式。

了解常見的耐久函式模式

在本文中，您將瞭解如何使用 Visual Studio 2022 在本機建立及測試「hello world」耐久函式。此函式會協調並鏈結對其他函式的呼叫。接著會將函式程式碼發佈至 Azure。這些工具是Visual Studio 2022 中 Azure 開發工作負載的一部分。

Visual Studio 2019 視窗具有耐久函式的螢幕快照。

必要條件

完成本教學課程：

安裝 Visual Studio 2022。請確定 也已安裝 Azure 開發 工作負載。 Visual Studio 2019 也支援 Durable Functions 開發，但 UI 和步驟不同。
確認您已安裝並執行 Azurite 模擬器。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

建立函式應用程式專案

Azure Functions 範本會建立專案，以發佈至 Azure 中的函式應用程式。函式應用程式可讓您將函式分組為邏輯單元，以便更輕鬆地管理、部署、調整及共用資源。

在 Visual Studio 中，從 [檔案] 選單中選取 [新增>專案]。
在 [ 建立新專案 ] 對話框中，搜尋 functions、選擇 Azure Functions 範本，然後選取 [ 下一步]。
輸入 專案的 [項目名稱 ]，然後選取 [ 確定]。專案名稱必須是 C# 命名空間的有效名稱，因此請勿使用底線、連字元或非虛構字元。

在 [ 其他資訊] 底下，使用影像後面之數據表中指定的設定。

在 Visual Studio 中建立新 Azure Functions 應用程式對話框的螢幕快照。

設定	建議的值	描述
函式背景工作	.NET 6	建立支援 .NET 6 和 Azure Functions Runtime 4.0 的函式專案。如需詳細資訊，請參閱如何以 Azure Functions 運行時間版本為目標。
Function	空的	建立空的函式應用程式。
儲存體帳戶	儲存體模擬器	長期函式狀態管理需要記憶體帳戶。

選取 [建立] 以建立空的函式專案。此專案具有執行函式所需的基本組態檔。

將函式新增至應用程式

下列步驟會使用範本在專案中建立耐久函式程序代碼。

以滑鼠右鍵按兩下 Visual Studio 中的項目，然後選取 [新增>Azure 函式]。
確認 已從 [新增] 功能表選取 [Azure 函式 ]，輸入 C# 檔案的名稱，然後選取 [ 新增]。
選取 Durable Functions 協調流程 範本，然後選取 [ 新增]。

新的耐久函式會新增至應用程式。開啟新的 .cs 檔案以檢視內容。這個耐久函式是具有下列方法的簡單函式鏈結範例：

方法	函數名稱	描述
`RunOrchestrator`	`<file-name>`	管理永久性協調流程。在此情況下，協調流程會啟動、建立清單，並將三個函式呼叫的結果新增至清單。當三個函式呼叫完成時，它會傳回清單。
`SayHello`	`<file-name>_Hello`	函式會傳回 hello。這是包含正在協調之商業規則的函式。
`HttpStart`	`<file-name>_HttpStart`	HTTP 觸發的函式，會啟動協調流程的實例，並傳回檢查狀態回應。

您現在可以在本機計算機上測試它，您現在已建立函式專案和耐久函式。

在本機測試函式

Azure Functions Core Tools 可讓您在本機開發電腦上執行 Azure Functions 專案。第一次從 Visual Studio 啟動函式時，系統會提示您安裝這些工具。

若要測試您的函式，請按 F5。如果出現提示，請接受 Visual Studio 所發出要下載及安裝 Azure Functions Core (CLI) 工具的要求。您可能也需要啟用防火牆例外狀況，讓工具可以處理 HTTP 要求。
從 Azure Functions 執行階段輸出複製函式的 URL。
將 HTTP 要求的 URL 貼到瀏覽器的網址列中，然後執行要求。下列顯示瀏覽器中回應函式所傳回的本機 GET 要求：

回應是 HTTP 函式的初始結果，讓我們知道長期協調流程已成功啟動。這還不是協調流程的最終結果。回應包含一些實用的 URL。讓現在我們查詢協調流程的狀態。

複製的 URL 值 statusQueryGetUri，將其貼到瀏覽器的網址列中，然後執行要求。

此要求會查詢協調流程執行個體的狀態。您必須取得如下所示的最終回應。此輸出會顯示實例已完成，並包含耐久函式的輸出或結果。

{
    "name": "Durable",
    "instanceId": "d495cb0ac10d4e13b22729c37e335190",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2019-11-02T07:07:40Z",
    "lastUpdatedTime": "2019-11-02T07:07:52Z"
}

若要停止偵錯，請按 Shift + F5。

確認函式在本機電腦上正確執行之後，就可以將專案發佈到 Azure。

將專案發佈至 Azure

在發佈專案之前，您必須在 Azure 訂用帳戶中擁有函式應用程式。您可以直接從 Visual Studio 建立函式應用程式。

在 [方案總管] 中，以滑鼠右鍵按一下專案並選取 [發行]。在 [目標] 中，選取 [Azure]，然後選取 [下一步]。
在 [特定目標]，選取 [Azure 函數應用程式 (Windows)] (這會建立在 Windows 上執行的函數應用程式)，然後選取 [下一步]。
在 [函式執行個體] 中，選擇 [建立新的 Azure 函式...]

使用下表中的指定值建立新的執行個體：

設定	值	描述
名稱	全域唯一的名稱	用以唯一識別新函式應用程式的名稱。接受此名稱或輸入新的名稱。有效字元：`a-z`、`0-9` 和 `-`。
訂用帳戶	您的訂用帳戶	要使用的 Azure 訂用帳戶。接受此訂用帳戶，或從下拉式清單中選取一個新的訂用帳戶。
資源群組	資源群組的名稱	您要在其中建立函數應用程式的資源群組。選取 [新建] 來建立新的資源群組。您也可以從下拉式清單中選擇現有的資源群組。
方案類型	耗用	當您將專案發佈至在取用方案中執行的函式應用程式時，您只需支付您的函式應用程式執行費用。其他主控方案會產生較高的成本。
地點	App Service 的位置	在區域中選擇位置，此位置應靠近您或靠近函式會存取的其他服務。
Azure 儲存體	一般用途的儲存體帳戶	函數執行階段所需的 Azure 儲存體帳戶。選取 [新增] 以設定一般用途的儲存體帳戶。您也可以選擇符合儲存體帳戶需求的現有帳戶。
Application Insights	Application Insights 執行個體	您應為函數應用程式啟用 Application Insights 整合。選取 [新增]，以在新的或現有的 Log Analytics 工作區中建立新的執行個體。您也可以選擇現有的執行個體。

[建立 App Service] 對話框的螢幕快照。

選取 [建立]，以在 Azure 中建立函數應用程式及其相關資源。資源的建立狀態會顯示在視窗左下方。
在 [函式執行個體] 中，請確定已核取 [從封裝檔案執行]。您的函式應用程式會使用已啟用從套件執行模式的 Zip 部署來部署。建議採用 Zip 部署來部署函式專案，可提高效能。
選取 [完成]，然後在 [發佈] 頁面上選取 [發佈]，將包含專案檔的套件部署到 Azure 中的新函數應用程式。

部署完成之後，[發佈] 索引標籤中會顯示 Azure 中函式應用程式的根 URL。
在 [發佈] 索引標籤的 [裝載] 區段中，選擇 [在 Azure 入口網站中開啟]。這會在 Azure 入口網站中開啟新的函數應用程式 Azure 資源。

在 Azure 中測試您的函式

從 [發佈設定檔] 頁面複製函式應用程式的基底 URL。 localhost:port以新的基底 URL 取代您在本機測試函式時所使用的 URL 部分。

呼叫長期函式 HTTP 觸發程式的 URL 必須具有下列格式：

https://<APP_NAME>.azurewebsites.net/api/<FUNCTION_NAME>_HttpStart
將 HTTP 要求的新 URL 貼到瀏覽器的網址列。使用已發佈的應用程式時，您必須取得與之前相同的狀態回應。

下一步

您已使用 Visual Studio 來建立及發布 C# 耐久函式應用程式。

了解常見的耐久函式模式

使用 C# 建立第一個長期函式

必要條件

建立本機專案

將函式新增至應用程式

在本機測試函式

登入 Azure

在 Azure 中建立函式應用程式

將專案部署至 Azure

在 Azure 中測試您的函式

下一步

必要條件

建立函式應用程式專案

將函式新增至應用程式

在本機測試函式

將專案發佈至 Azure

在 Azure 中測試您的函式

下一步

其他資源