独立版 Durable Functions PowerShell SDK 指南

建议使用独立的 Durable Functions PowerShell SDK（AzureFunctions.PowerShell.Durable.SDK）来创建 PowerShell 的 Durable Functions 应用。 它将内置 SDK 替换为更快的重播逻辑（与 C# 独立 SDK 相同的引擎）、独立版本控制以及改进的异常处理、null 值处理和序列化。 内置 SDK 仍可用于 PowerShell 7.4 及更早版本，但在 PowerShell 辅助角色的未来主要版本中将被删除。

迁移清单

使用以下清单跟踪每个迁移步骤的进度：

安装独立 SDK

按照以下步骤在现有应用中安装和启用独立 SDK。

验证先决条件

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

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

启用独立 SDK

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

• 名称：ExternalDurablePowerShellSDK
• 值："true"

此应用程序设置禁用 PowerShell 7.4 及更高版本的内置 Durable SDK，强制工作者使用外部 SDK。

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

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

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

安装 SDK 包

有两个选项可用于安装 SDK 包。 对于大多数应用建议使用 托管依赖项 ，但如果需要固定特定版本或您的部署不支持托管依赖项，请将 模块与应用内容捆绑在一起。 只需要一个选项。

选项 1：使用托管依赖项（建议）

若要将 SDK 安装为托管依赖项，请遵循 托管依赖项指南。 首先，确保host.json包含一个managedDependency部分，其中enabled的设置为true。

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

然后为你的requirements.psd1文件中的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 模块

若要将 SDK 与应用捆绑在一起 ".\Modules" ，请将 SDK 包放在应用的根目录中。 有关详细信息，请参阅 在应用内容中包含模块。

从应用程序根目录创建目录并下载 SDK：

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

导入 SDK

将以下行添加到 profile.ps1 文件，以在每次冷启动时导入 SDK：

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

运行你的应用程序

启动应用程序，使用func host start。 独立 SDK 现已处于活动状态。

从内置 SDK 迁移

如果要从内置 SDK 迁移现有应用，请查看以下界面和行为更改。

新 cmdlet

已修改的 CmdLet

行为变更

Wait-DurableTask 中的异常处理

使用 Wait-DurableTask（扇出/扇入模式）计划的活动引发的异常不再被无提示地忽略。 该 cmdlet 现在将异常传播到协调器，使您能够在代码中处理它。

内置 SDK — 异常被无提示地忽略：

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

独立 SDK — 异常传播到协调器：

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Wait-DurableTask 结果中保留的空值

Null 值不再从 Wait-DurableTask (WhenAll) 调用的结果列表中删除。 没有 -Any 标志的成功调用现在将返回一个与计划任务数量相同大小的数组，其中包括返回 null 的活动的 $null 项。

内置 SDK — null 结果已删除：

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

独立 SDK — 保留空结果：

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

SDK 参考

有关完整的 cmdlet 参考，请参阅 AzureFunctions.PowerShell.Durable.SDK 模块。 导入模块后，还可以运行 Get-Help *-Durable* 以列出所有可用的 cmdlet，或 Get-Help <cmdlet-name> -Full 详细使用情况。

获取支持

报告 SDK GitHub 存储库中的 bug 和功能请求。

后续步骤

• 使用 PowerShell 创建Durable Functions应用
• Durable Functions 模式和概念
• 适用于 Azure Functions 的 PowerShell 开发人员参考