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

發行項
06/16/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。
確定您已安裝 .NET Core SDK 3.1 版或更新版本。

如果您沒有 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，以及將 Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet 套件的參考新增至 .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。讓現在我們查詢協調流程的狀態。

複製 statusQueryGetUri 的 URL 值，將其貼在瀏覽器的網址列中，然後執行要求。或者，您也可以繼續使用 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 帳戶...]。學生可以選擇 [建立 Microsoft Azure 學生版帳戶...]。
當在瀏覽器中收到提示時，請使用您的 Azure 帳戶認證選擇 Azure 帳戶並登入。如果您建立新的帳戶，可以在帳戶建立之後登入。
成功登入之後，即可關閉新的瀏覽器視窗。屬於您 Azure 帳戶的訂用帳戶會顯示在提要欄位中。

在 Azure 中建立函式應用程式

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

在 Visual Studio Code 中，按 F1 開啟命令選擇區，並搜尋並執行命令 Azure Functions: Create Function App in Azure...。

提示中會提供下列資訊：

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

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

建立 Azure 資源的記錄

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

提示

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

將專案部署至 Azure

重要

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

在命令選擇區中，搜尋並執行命令 Azure Functions: Deploy to Function App...。
選取您剛才建立的函式應用程式。當系統提示您覆寫先前的部署時，請選取 [部署]，將函式程式碼部署至新的函數應用程式資源。
部署完成時，選取 [檢視輸出] 即可檢視建立和部署結果，包括您所建立的 Azure 資源。如果您錯過通知，請選取右下角的鈴鐺圖示，以再次查看。

在 Azure 中測試您的函式

從 [輸出] 面板中複製 HTTP 觸發程序的 URL。呼叫 HTTP URL 觸發函式的 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 Function]。
確認已從 [新增] 功能表中選取 [Azure Function]，輸入您的 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。讓現在我們查詢協調流程的狀態。

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

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

{
    "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。使用新的基底 URL，取代在本機測試函式時所使用之 URL 的 localhost:port 部分。

呼叫耐久函式 HTTP 觸發程序的 URL 必須採用下列格式：

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

下一步

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

了解常見的耐久函式模式

共用方式為

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

必要條件

建立本機專案

將函式新增至應用程式

在本機測試函式

在 Azure 中建立函式應用程式

將專案部署至 Azure

在 Azure 中測試您的函式

下一步

必要條件

建立函式應用程式專案

將函式新增至應用程式

在本機測試函式

將專案發佈至 Azure

在 Azure 中測試您的函式

下一步

意見反應

意見反應

其他資源