你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

独立版 Durable Functions PowerShell SDK 指南

2025-07-23

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 及更早版本。

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

安装和启用 SDK

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

Prerequisites

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

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

选择加入独立 DF SDK

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

名称：ExternalDurablePowerShellSDK
值： "true"

此应用程序设置将禁用适用于 PowerShell 7.4 及更高版本的内置 Durable 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 下载到 modules 目录中，如下所示：

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

导入 SDK

最后一步是将 SDK 导入代码的会话中。为此，请通过 profile.ps1 文件中的 Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop 导入 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，允许用户在其工作流中使用子协调器。
Suspend-DurableOrchestration 和 Resume-DurableOrchestration 是允许用户分别暂停和恢复编排的新 cmdlet。

已修改的 CmdLet

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

行为变更

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

获取支持并提供反馈

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