快速入门：设置 Durable Functions 应用以使用 MSSQL 存储提供程序

项目
11/25/2024

使用 Durable Functions（Azure Functions 的一项功能）在无服务器环境中编写有状态函数。 Durable Functions 管理应用程序中的状态、检查点和重启。

Durable Functions 支持多个存储提供程序（也称为“后端”），用于存储业务流程和实体运行时状态。默认情况下，新项目配置为使用 Azure 存储提供程序。在本快速入门中，你需将 Durable Functions 应用配置为使用 Microsoft SQL Server (MSSQL) 存储提供程序。

注意

MSSQL 后端旨在最大程度地提高应用程序可移植性和对数据的控制。它使用 Microsoft SQL Server 来保存所有任务中心数据，以便用户获得现代企业级数据库管理系统 (DBMS) 基础结构的优势。若要详细了解何时使用 MSSQL 存储提供程序，请参阅存储提供程序概述。
目前不支持跨存储提供程序迁移任务中心数据。具有现有的运行时数据的函数应用在切换到 MSSQL 后端后，会从新的空任务中心开始。同样，如果切换到其他存储提供程序，则使用 MSSQL 创建的任务中心内容无法保留。
目前，在 Flex 消耗计划上运行时，Durable Functions 不支持 MSSQL 后端。

先决条件

以下步骤假定你有现有的 Durable Functions 应用，并且熟悉如何操作它。

具体而言，本快速入门假定你已经：

在本地计算机上创建了 Azure Functions 项目。
使用业务流程协调程序函数和触发 Durable Functions 应用的客户端函数向项目添加了 Durable Functions。
配置项目进行本地调试。

如果不满足这些先决条件，建议从以下快速入门之一开始：

添加持久任务 MSSQL 扩展（仅 .NET）

注意

如果你的应用使用扩展捆绑包，请跳过本部分。扩展捆绑包无需手动进行扩展管理。

首先，从 NuGet 安装最新版本的 Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer MSSQL 存储提供程序扩展。对于 .NET，请在 .csproj 文件中添加对扩展的引用，然后生成项目。还可以使用 dotnet add package 命令添加扩展包。

可以使用以下 Azure Functions Core Tools CLI 命令安装扩展：

func extensions install --package <package name depending on your worker model> --version <latest version>

有关通过 Core Tools CLI 安装 Azure Functions 扩展的详细信息，请参阅 func extensions install。

设置数据库

注意

如果你已有与 MSSQL 兼容的数据库，则可以跳过本节以及有关设置基于 Docker 的本地数据库的下一节。

由于 MSSQL 后端旨在实现可移植性，因此可以使用多个选项来设置后备数据库。例如，可以设置本地 SQL Server 实例、使用完全托管的 Azure SQL Database 实例，或使用任何其他 SQL Server 兼容的托管选项。

还可以在本地 Windows 计算机上使用 SQL Server Express 进行本地脱机开发，或使用在 Docker 容器中运行的 SQL Server Docker 映像。

本快速入门重点介绍如何使用 SQL Server Docker 映像。

设置本地基于 Docker 的 SQL Server 实例

要运行这些步骤，你需要在本地计算机上安装 Docker。可以使用以下 PowerShell 命令在 Docker 上设置本地 SQL Server 数据库。可以在 Windows、macOS 或 Linux 上安装 PowerShell。

# primary parameters
$pw        = "yourStrong(!)Password"
$edition   = "Developer"
$port      = 1433
$tag       = "2019-latest"
$dbname    = "DurableDB"
$collation = "Latin1_General_100_BIN2_UTF8"

# pull the image from the Microsoft container registry
docker pull mcr.microsoft.com/mssql/server:$tag

# run the image and provide some basic setup parameters
docker run --name mssql-server -e 'ACCEPT_EULA=Y' -e "MSSQL_SA_PASSWORD=$pw" -e "MSSQL_PID=$edition" -p ${port}:1433 -d mcr.microsoft.com/mssql/server:$tag

# wait a few seconds for the container to start...

# create the database with strict binary collation
docker exec -d mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "CREATE DATABASE [$dbname] COLLATE $collation"

运行这些命令后，应在 Docker 上运行本地 SQL Server 并侦听端口 1443。如果端口 1443 与其他服务冲突，你可以在将变量 $port 更改为其他值后重新运行这些命令。

如果在运行最后一个命令时收到此错误：

Error response from daemon: OCI runtime exec failed: exec failed: unable to start container process: exec: "/opt/mssql-tools/bin/sqlcmd": stat /opt/mssql-tools/bin/sqlcmd: no such file or directory: unknown

文件夹 /opt/mssql-tools/bin/sqlcmd 可能不存在。打开 Docker Desktop，选择 SQL Server Docker 容器，选择“文件”并浏览 mssql-tools 文件夹。此文件夹可能具有其他名称，例如 /opt/mssql-tools18/bin/sqlcmd。相应地更新最后一行代码，并重新运行。

注意

若要停止和删除正在运行的容器，可以分别使用 docker stop <containerName> 和 docker rm <containerName>。可以使用这些命令重新创建容器，并在完成本快速入门后停止容器。如需更多帮助，请运行 docker --help。

若要验证数据库安装，请使用此 Docker 命令查询新的 SQL 数据库：

docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -U sa -P "$pw" -Q "SELECT name FROM sys.databases"

如果数据库设置成功完成，数据库的名称（例如 DurableDB）将显示在命令行输出中：

name

--------------------------------------------------------------
master

tempdb

model

msdb

DurableDB

将 SQL 连接字符串添加到 local.settings.json

MSSQL 后端需要连接字符串才能访问数据库。获取连接字符串的方式主要取决于特定的 MSSQL 服务器提供程序。如需了解获取连接字符串的方式的信息，请查看特定提供程序的文档。

如果使用上述 Docker 命令而不更改任何参数，则连接字符串为：

Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;

获取连接字符串后，将其添加到 local.settings.json 中的变量，以在本地开发期间使用它。

下面是将默认基于 Docker 的 SQL Server 实例连接字符串分配给变量 SQLDB_Connection 的示例 local.settings.json：

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true", 
    "SQLDB_Connection": "Server=localhost,1433;Database=DurableDB;User Id=sa;Password=yourStrong(!)Password;",
    "FUNCTIONS_WORKER_RUNTIME": "<dependent on your programming language>"
  }
}

注意

FUNCTIONS_WORKER_RUNTIME 的值取决于你使用的编程语言。有关详细信息，请参阅运行时参考。

更新 host.json

编辑 host.json 文件的存储提供程序部分，将 type 设置为 mssql。你还必须在 connectionStringName 下指定连接字符串变量名称 SQLDB_Connection。将 createDatabaseIfNotExists 设置为 true。此设置将使用排序规则 Latin1_General_100_BIN2_UTF8 创建名为 DurableDB 的数据库（如果它尚不存在）。

{
  "version": "2.0",
  "extensions": {
    "durableTask": {
      "storageProvider": {
        "type": "mssql",
        "connectionStringName": "SQLDB_Connection",
        "createDatabaseIfNotExists": true 
        }
    }
  },
  "logging": {
    "logLevel": {
      "DurableTask.SqlServer": "Warning",
      "DurableTask.Core": "Warning"
    }
  }
}

此代码示例是一个相对基本的 host.json 示例。稍后你可能需要添加参数。

本地测试

你的应用现已准备好进行本地开发。可以启动函数应用来测试它。启动该应用的一种方法是在你的应用程序的根目录中运行 func host start，然后执行基本的业务流程协调程序函数。

函数应用在运行期间，它会更新已配置的 SQL 数据库中的运行时状态。可以使用 SQL 查询接口测试它是否按预期工作。例如，在基于 docker 的本地 SQL Server 容器中，可以使用以下 Docker 命令查看业务流程实例的状态：

docker exec -it mssql-server /opt/mssql-tools/bin/sqlcmd -S . -d $dbname -U sa -P "$pw"  -Q "SELECT TOP 5 InstanceID, RuntimeStatus, CreatedTime, CompletedTime FROM dt.Instances"

运行业务流程后，查询将返回类似于此示例的结果：

InstanceID                           RuntimeStatus        CreatedTime                   CompletedTime
------------------------------------ -------------------- ----------------------------- ----------------------------
9fe1ea9d109341ff923621c0e58f215c     Completed            2022-11-16 21:42:39.1787277   2022-11-16 21:42:42.3993899

在 Azure 中运行应用

要在 Azure 中运行应用，你需要一个可公开访问的 SQL Server 实例。可以通过创建 Azure SQL 数据库来获取。

创建 Azure SQL 数据库

注意

如果你已有 Azure SQL 数据库或者你想使用的其他可公开访问的 SQL Server 实例，则可以转到下一节。

在 Azure 门户中，可以创建 Azure SQL 数据库。配置数据库时，请确保将“数据库排序规则”的值（在“其他设置”下）设置为 Latin1_General_100_BIN2_UTF8。

注意

如果你是首次使用 Azure，那么 Microsoft 会提供一个 12 个月的 Azure 订阅帐户。

可以通过转到 Azure 门户中的数据库概述窗格来获取 Azure SQL 数据库的连接字符串。然后选择“设置”下的“连接字符串”，并获取“ADO.NET”连接字符串。请确保在提供的模板中提供你的密码。

下面是有关如何在门户中获取 Azure SQL 连接字符串的示例：

显示 Azure 门户中的 Azure 连接字符串的屏幕截图。

在 Azure 门户中，连接字符串会删除数据库的密码：它被替换为 {your_password}。将该占位符替换为你在本节前面用于创建数据库的密码。如果忘记了密码，可以通过转到 Azure 门户中的数据库概述窗格来重置它。在“概要”视图中，选择你的服务器名称。然后，选择“重置密码”。如需示例，请参考以下屏幕截图。

显示 Azure SQL 数据库视图的屏幕截图，其中突出显示了“服务器名称”选项。

显示 SQL Server 视图的屏幕截图，其中“重置密码”可见。

将连接字符串添加为应用程序设置

接下来，将你的数据库的连接字符串添加为应用程序设置。若要在 Azure 门户中添加它，请先转到你的 Azure Functions 应用视图。在“配置”下，选择“新建应用程序”设置。分配 SQLDB_Connection 以映射到可公开访问的连接字符串。如需示例，请参考以下屏幕截图。

显示突出显示了“数据库”窗格和“新建应用程序设置”的屏幕截图。

显示输入连接字符串设置名称和其值的屏幕截图。

部署

现在可以将函数应用部署到 Azure，并在其中运行测试或工作负载。若要验证 MSSQL 后端是否已正确配置，可以查询数据库中的任务中心数据。

例如，可以在 SQL 数据库的概述窗格中查询你的业务流程实例。选择“查询编辑器”，进行身份验证，然后运行以下查询：

SELECT TOP 5 InstanceID, RuntimeStatus, CreatedTime, CompletedTime FROM dt.Instances

运行简单的业务流程协调程序后，你应会看到至少一个结果，如以下示例所示：

显示 SQL 查询的 Azure SQL 查询编辑器结果的屏幕截图。

有关 Durable Functions 应用任务 MSSQL 后端体系结构、配置和工作负载行为的详细信息，请参阅 MSSQL 存储提供程序文档。

通过