独立版 Durable Functions PowerShell SDK 指南

2025/07/11

Durable Functions （DF） PowerShell SDK 现已作为 PowerShell 库中的独立模块提供： AzureFunctions.PowerShell.Durable.SDK 此 SDK 现已 正式发布（正式版）， 建议使用 PowerShell 创作 Durable Functions 应用。在本文中，我们将介绍此更改的好处，以及采用此新包时预期的更改。

独立版 SDK 背后的动机

以前的 DF SDK 已内置于 PowerShell 语言工作者中。此方法的优势是，Azure Functions PowerShell 用户可以开箱即用地创作 Durable Functions 应用。但是，它也存在各种缺点：

新功能、bug 修复和其他更改取决于 PowerShell 辅助角色的发布节奏。
由于 PowerShell 工作器的自动升级特性，DF SDK 在修复 bug 时需要更为保守，因为任何行为上的变更都可能构成重大更改。
内置 DF SDK 使用的重播算法已过时：其他 DF SDK 已使用更快、更可靠的实现。

通过创建独立版 DF PowerShell SDK 包，我们能够克服这些缺点。利用此新的独立版 SDK 包具有以下优势：

此 SDK 包含许多强烈要求的改进，例如更好的异常和 null 值处理以及序列化修复。
该软件包的版本独立于 PowerShell 运行程序。这允许用户在新增功能和修补程序可用时立即引入它们，同时避免自动升级造成的中断性变更。
重播逻辑的速度更快、更可靠：它使用与适用于 C# 的 DF 隔离 SDK 相同的重播引擎。

内置 DF PowerShell SDK 的弃用计划

PowerShell 辅助角色中的内置 DF SDK 仍可用于 PowerShell 7.4 及更早版本。

我们计划最终发布一个不带内置 SDK 的 PowerShell 工作器新主版本。届时，用户将需要使用此独立包单独安装 SDK；安装步骤如下所述。

安装和启用 SDK

请参阅此部分，了解如何在现有应用中安装和启用新的独立版 SDK。

先决条件

独立版 PowerShell SDK 需要以下最低版本：

Azure Functions 运行时 v4.16+
Azure Functions Core Tools v4.0.5095+（如果在本地运行）
适用于 PowerShell 7.2 或更高版本的 Azure Functions PowerShell 应用

选择加入独立 DF SDK

需要以下应用程序设置才能运行独立的 PowerShell SDK：

名称：ExternalDurablePowerShellSDK
值："true"

此应用程序设置将禁用适用于 PowerShell 7.2 及更高版本的内置持久 SDK，强制辅助角色使用外部 SDK。

如果使用 Azure Functions Core Tools 在本地运行，则应将此设置添加到 local.settings.json 文件中。如果在 Azure 中运行，请使用所选工具执行以下步骤：

将 <FUNCTION_APP_NAME> 和 <RESOURCE_GROUP_NAME> 分别替换为函数应用名称和资源组名称。

az functionapp config appsettings set --name <FUNCTION_APP_NAME> --resource-group <RESOURCE_GROUP_NAME> --settings ExternalDurablePowerShellSDK="true"

将 <FUNCTION_APP_NAME> 和 <RESOURCE_GROUP_NAME> 分别替换为函数应用名称和资源组名称。

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"ExternalDurablePowerShellSDK" = "'true'"}

安装和导入 SDK

安装 SDK 包有两个选项：使用托管依赖项进行安装，或与应用内容捆绑安装。在本部分，我们将介绍这两个选项，但只需要其中一个选项。

安装选项 1：使用托管依赖项

若要将 SDK 作为托管依赖项进行安装，需要遵循托管依赖项指南。请查看指南了解详细信息。总之，首先需要确保 host.json 包含 managedDependency 部分，且 enabled 属性设置为 true。下面是满足此要求的示例 host.json：

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  },
}

然后，只需在 requirements.psd1 文件中指定 DF SDK 的条目，如以下示例所示：

# This file enables modules to be automatically managed by the Functions service.
# See https://aka.ms/functionsmanageddependency for additional information.
#
@{
    # For latest supported version, go to 'https://www.powershellgallery.com/packages/AzureFunctions.PowerShell.Durable.SDK/'.
    'AzureFunctions.PowerShell.Durable.SDK' = '2.*'
}

安装选项 2：在应用内容中包含 SDK 模块

若要在应用内容中包含独立的 DF SDK，需要遵循有关在应用内容中包含模块的指南。有关详细信息，请务必查看上述文档。总之，需要将 SDK 包放在应用根目录的 ".\Modules" 目录中。

例如，从应用程序的根目录中创建 ".\Modules" 目录后，可以将独立版 SDK 下载到模块目录中，如下所示：

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

导入 SDK

最后一步是将 SDK 导入代码会话。为此，请在 Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop 文件中通过 profile.ps1 导入 PowerShell SDK。例如，如果应用是通过模板搭建基架的，则 profile.ps1 文件最终可能类似于：

# Azure Functions profile.ps1
#
# This profile.ps1 will get executed every "cold start" of your Function App.
# "cold start" occurs when:
#
# * A Function App starts up for the very first time
# * A Function App starts up after being de-allocated due to inactivity
#
# You can define helper functions, run commands, or specify environment variables
# NOTE: any variables defined that are not environment variables will get reset after the first execution

# Authenticate with Azure PowerShell using MSI.
# Remove this if you are not planning on using MSI or Azure PowerShell.
if ($env:MSI_SECRET) {
    Disable-AzContextAutosave -Scope Process | Out-Null
    Connect-AzAccount -Identity
}

# Uncomment the next line to enable legacy AzureRm alias in Azure PowerShell.
# Enable-AzureRmAlias

# You can also define functions or aliases that can be referenced in any of your PowerShell functions.

# Import standalone PowerShell SDK
Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

以下是使用下一个 PowerShell SDK 所需的所有步骤。在你的终端中，通过 func host start 正常运行应用以开始使用 SDK。

SDK 参考

有关 SDK cmdlet 及其参数的完整参考，请参阅 AzureFunctions.PowerShell.Durable.SDK 模块。

还可以使用 Get-Help cmdlet 获取 SDK cmdlet 的详细说明。为此，首先需要导入模块，如上一部分所示。之后，可以运行以下命令来获取 cmdlet 的完整列表：

Get-Help *-Durable*

若要获取有关特定 cmdlet 的详细帮助，包括使用示例，请运行：

Get-Help Invoke-DurableOrchestration -Full

迁移指南

在本部分，我们将介绍使用新 SDK 时可以预期的界面和行为变更。

新 cmdlet

Invoke-DurableSubOrchestrator 是一个新的 cmdlet，允许用户在其工作流中使用子编排器。
新 cmdlet Suspend-DurableOrchestration 和 Resume-DurableOrchestration 分别允许用户暂停和恢复编排。

修改的 cmdlet

该 Get-DurableTaskResult cmdlet 现在仅接受单个 Task 作为参数，而不是接受任务列表。
cmdlet New-DurableRetryOptions 重命名为 New-DurableRetryPolicy （提供旧名称的别名以实现向后兼容性）。

行为变更

使用 Wait-DurableTask 计划的活动（例如在扇出/扇入模式下）引发的异常不再被静默忽略。相反，在异常中，cmdlet 会将该异常传播到业务流程协调程序，以便可由用户代码处理。
将不再从 Wait-DurableTask（即 WhenAll）调用的结果列表中删除 Null 值。这意味着，成功调用不带 Wait-DurableTask 标志的 -Any 应该会返回一个与其计划的任务数大小相同的数组。

获取支持并提供反馈

请向 SDK 的 GitHub 存储库报告任何反馈和建议。

通过