使用 C# 创建你的第一个持久函数

项目
06/02/2023

Durable Functions 是 Azure Functions 的一个扩展，可用于在无服务器环境中编写有状态函数。该扩展可用于管理状态、检查点和重启。

本文介绍了如何使用 Visual Studio Code 在本地创建并测试“hello world”持久函数。此函数将协调对其他函数的调用并将其链接在一起。然后可将函数代码发布到 Azure。这些工具作为 Visual Studio Code Azure Functions 扩展的一部分提供。

Screenshot of Visual Studio Code window with a durable function.

先决条件

为完成此教程：

安装 Visual Studio Code。
安装以下 Visual Studio Code 扩展：
- Azure Functions
- C#
确保安装了最新版本的 Azure Functions Core Tools。
Durable Functions 需要一个 Azure 存储帐户。需要一个 Azure 订阅。
请确保安装 3.1 或更高版本的 .NET Core SDK。

如果没有 Azure 订阅，可在开始前创建一个试用帐户。

创建本地项目

在本部分，你将使用 Visual Studio Code 创建一个本地 Azure Functions 项目。

在 Visual Studio Code 中，按 F1（或 Ctrl/Cmd+Shift+P）打开命令面板。在命令面板中，搜索并选择 Azure Functions: Create New Project...。
为项目选择一个空文件夹位置，然后选择“选择”。

按照提示提供以下信息：

Prompt	值	说明
选择函数应用项目的语言	C#	创建本地 C# Functions 项目。
选择版本	Azure 函数 v4	仅当尚未安装 Core Tools 时，才会出现此选项。在本例中，当你首次运行应用时即已安装 Core Tools。
为项目的第一个函数选择模板	暂时跳过
选择打开项目的方式	在当前窗口中打开	在所选的文件夹中重新打开 Visual Studio Code。

Visual Studio Code 会根据需要安装 Azure Functions Core Tools。它还会在某个文件夹中创建一个函数应用项目。此项目包含 host.json 和 local.settings.json 配置文件。

向应用中添加函数

以下步骤使用模板在项目中创建持久函数代码。

在命令面板中，搜索并选择 Azure Functions: Create Function...。

按照提示提供以下信息：

Prompt	值	说明
选择函数的模板	DurableFunctionsOrchestration	创建 Durable Functions 业务流程
提供函数名称	HelloOrchestration	在其中创建函数的类的名称
提供命名空间	Company.Function	所生成类的命名空间

当 Visual Studio Code 提示选择存储帐户时，请选择“选择存储帐户”。按照提示提供以下信息，并在 Azure 中创建新的存储帐户：

Prompt	值	说明
选择订阅	订阅的名称	选择 Azure 订阅
选择存储帐户	新建存储帐户
输入新存储帐户的名称	唯一名称	要创建的存储帐户的名称
选择资源组	唯一名称	要创建的资源组名称
选择一个位置	region	选择离你较近的区域

包含新函数的类会添加到此项目。 Visual Studio Code 还将存储帐户连接字符串添加到 local.settings.json，并将对 Microsoft.Azure.WebJobs.Extensions.DurableTask NuGet 包的引用添加到 .csproj 项目文件。

打开新的 HelloOrchestration.cs 文件，查看其内容。此持久函数是一个简单的函数链接示例，包含以下方法：

方法	FunctionName	说明
`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 之类的工具向 URL 终结点发送一个 HTTP POST 请求。

响应是 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 帐户...”。
在浏览器中出现提示时，请选择你的 Azure 帐户，并使用你的 Azure 帐户凭据登录。如果创建新帐户，你可以在创建帐户后登录。
成功登录后，可以关闭新浏览器窗口。属于你的 Azure 帐户的订阅将显示在边栏中。

在 Azure 中创建函数应用

在本部分中，你将在 Azure 订阅中创建函数应用和相关的资源。

在活动栏中选择 Azure 图标。然后在“资源”区域中，选择 + 图标，然后选择“在 Azure 中创建函数应用”选项。

根据提示提供以下信息：

Prompt	选择
选择订阅	选择要使用的订阅。如果你在“资源”下只有一个订阅可见，则你不会看到此提示。
输入函数应用的全局唯一名称	键入在 URL 路径中有效的名称。将对你键入的名称进行验证，以确保其在 Azure Functions 中是唯一的。
选择一个运行时堆栈	选择你一直在本地运行的语言版本。
选择新资源的位置	为了获得更好的性能，请选择你附近的区域。

在 Azure 中创建各个资源时，该扩展会在“Azure: 活动日志”面板中显示这些资源的状态。

Log of Azure resource creation

创建完成时，会在你的订阅中创建以下 Azure 资源。资源基于你的函数应用名称进行命名：
- 一个资源组：相关资源的逻辑容器。
- 一个标准 Azure 存储帐户：用于维护项目的状态和其他信息。
- 一个函数应用：提供用于执行函数代码的环境。可以通过函数应用将函数分组为逻辑单元，以便在同一托管计划中更轻松地管理、部署和共享资源。
- 一个应用服务计划：用于你的函数应用的基础主机。
- 一个连接到函数应用的 Application Insights 实例，用于跟踪你的函数在应用中的使用情况。
创建函数应用并应用了部署包之后，会显示一个通知。

提示

默认情况下，会根据你提供的函数应用名称创建函数应用所需的 Azure 资源。默认情况下，还会在函数应用所在的新资源组中创建这些资源。如果要自定义这些资源的名称或重复使用现有资源，则需要使用高级创建选项来发布项目。

将项目部署到 Azure

重要

部署到现有函数应用将始终覆盖该应用在 Azure 中的内容。

在活动栏中选择 Azure 图标，然后在“工作区”区域中选择你的项目文件夹，并选择“部署...”按钮。
选择“部署到函数应用...”，然后选择刚刚创建的函数应用，选择“部署”。
在部署完成后，选择“查看输出”以查看创建和部署结果，其中包括你创建的 Azure 资源。如果错过了通知，请选择右下角的响铃图标以再次查看。

在 Azure 中测试函数

从“输出” 面板复制 HTTP 触发器的 URL。调用 HTTP 触发的函数的 URL 必须采用以下格式：

https://<functionappname>.chinacloudsites.cn/api/HelloOrchestration_HttpStart
将 HTTP 请求的这个新 URL 粘贴到浏览器的地址栏中。必须得到与之前使用已发布的应用时相同的状态响应。

后续步骤

你已使用 Visual Studio Code 创建并发布了一个 C# 持久函数应用。

了解常见的持久函数模式

本文介绍了如何使用 Visual Studio 2022 在本地创建并测试“hello world”持久函数。此函数将协调对其他函数的调用并将其链接在一起。然后将函数代码发布到 Azure。 Visual Studio 2022 中的 Azure 开发工作负载已随附这些工具。

Screenshot of Visual Studio 2019 window with a durable function.

先决条件

为完成此教程：

安装 Visual Studio 2022。确保还安装了 Azure 开发工作负荷。 Visual Studio 2019 也支持 Durable Functions 开发，但 UI 和步骤不同。
验证 Azure 模拟器是否已安装且正在运行。

如果没有 Azure 订阅，可在开始前创建一个试用帐户。

创建函数应用项目

Azure Functions 模板创建一个项目，该项目可发布到 Azure 中的函数应用。函数应用可将函数分组为逻辑单元，以便更轻松地管理、部署、缩放和共享资源。

在 Visual Studio 中，从“文件”菜单中选择“新建”>“项目”。
在“创建新项目”对话框中，搜索 functions，选择“Azure Functions”模板，然后选择“下一步”。
为项目输入项目名称，然后选择“确定”。项目名称必须可以充当 C# 命名空间，因此请勿使用下划线、连字符或非字母数字字符。

在“其他信息”下，使用映像后面的表中指定的设置。

Screenshot of create a new Azure Functions Application dialog in Visual Studio.

设置	建议值	说明
Functions 辅助角色	.NET 6	创建支持 .NET 6 和 Azure Functions 运行时 4.0 的函数项目。有关详细信息，请参阅如何指向 Azure Functions 运行时版本。
Function	空	创建一个空的函数应用。
存储帐户	存储模拟器	要进行持久函数状态管理，需要一个存储帐户。

选择“创建”以创建一个空的函数项目。此项目具有运行函数所需的基本配置文件。

向应用中添加函数

以下步骤使用模板在项目中创建持久函数代码。

在 Visual Studio 中右键单击该项目并选择“添加”>“新建 Azure 函数”。
确认从“添加”菜单中选择了“Azure 函数”，输入 C# 文件的名称，然后选择“添加”。
请选择“Durable Functions 业务流程”模板，然后选择“添加”。

一个新的持久函数将添加到应用中。打开新的 .cs 文件以查看内容。此持久函数是一个简单的函数链接示例，包含以下方法：

方法	FunctionName	说明
`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 函数…”。

使用下表中指定的值创建新的实例：

设置	值	描述
名称	全局唯一名称	用于唯一标识新 Function App 的名称。接受此名称或输入新名称。有效的字符是 `a-z`、`0-9` 和 `-`。
订阅	你的订阅	要使用的 Azure 订阅。接受此订阅，或从下拉列表中选择一个新订阅。
资源组	资源组的名称	你要在其中创建函数应用的资源组。从下拉列表中选择一个现有资源组，或者选择“新建”来创建一个新的资源组。
计划类型	消耗	将项目发布到在消耗计划中运行的函数应用时，只需为函数应用的执行付费。其他托管计划会产生更高的成本。
位置	应用服务的位置	在靠近你或者靠近函数访问的其他服务的区域中选择一个位置。
Azure 存储	常规用途存储帐户	Functions 运行时需要 Azure 存储帐户。选择“新建”即可配置常规用途存储帐户。也可选择一个符合存储帐户要求的现有帐户。

Screenshot of Create App Service dialog.

选择“创建”，在 Azure 中创建一个函数应用及其相关资源。资源创建的状态将显示在窗口左下角。
在“函数实例”中，确保已选中“从包文件运行”。启用从包运行模式，函数应用将使用 Zip 部署进行部署。建议为你的函数项目使用 Zip 部署方法，因为它可提高性能。
选择“完成”，然后在“发布”页面上选择“发布”，将包含项目文件的包部署到 Azure 中的新函数应用。

部署完成后，Azure 中函数应用的根 URL 将显示在“发布”选项卡中。
在“发布”选项卡中的“托管”部分中，选择“在 Microsoft Azure 门户中打开”。此操作会在 Microsoft Azure 门户中打开新的函数应用 Azure 资源。

在 Azure 中测试函数

从“发布”配置文件页复制函数应用的基 URL。将 URL 的 localhost:port 部分（在本地测试函数时使用）替换为新的基 URL。

调用持久函数 HTTP 触发器的 URL 必须采用以下格式：

https://<APP_NAME>.chinacloudsites.cn/api/<FUNCTION_NAME>_HttpStart
将 HTTP 请求的这个新 URL 粘贴到浏览器的地址栏中。必须得到与之前使用已发布的应用时相同的状态响应。

后续步骤

你已使用 Visual Studio 创建并发布了一个 C# 持久函数应用。

了解常见的持久函数模式

通过

使用 C# 创建你的第一个持久函数

先决条件

创建本地项目

向应用中添加函数

在本地测试函数

登录 Azure

在 Azure 中创建函数应用

将项目部署到 Azure

在 Azure 中测试函数

后续步骤

先决条件

创建函数应用项目

向应用中添加函数

在本地测试函数

将项目发布到 Azure

在 Azure 中测试函数

后续步骤

其他资源