独立版 Durable Functions PowerShell SDK 指南

项目
10/04/2023

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、7.2 及更低版本。

我们计划最终发布 PowerShell 辅助角色的新主版本，不带内置 SDK。届时，用户将需要使用此独立包单独安装 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 包含 enabled 属性设置为 true 的 managedDependency 部分。下面是满足此要求的示例 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' = '1.*'
}

安装选项 2：使用自定义模块

若要将独立版 DF SDK 作为自定义模块进行安装，需要遵循有关创建应用级模块文件夹的指导。有关详细信息，请务必查看上述文档。总之，需要将 SDK 包放在应用根目录的 ".\Modules" 目录中。

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

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 时可以预期的界面和行为变更。

新 CmdLet

Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> 是一个新 CmdLet，允许用户在其工作流中使用子业务流程协调程序。

已修改的 CmdLet

CmdLet Get-DurableTaskResult -Task <task> 现在仅接受单个任务作为其参数，而不是接受任务列表。

行为变更

对于由通过 Wait-DurableTask 安排的活动引发的异常（例如在扇出/扇入模式中），将不再以无提示方式忽略它们。相反，在出现异常时，CmdLet 会将该异常传播到业务流程协调程序，以便用户代码能够进行处理。
将不再从 Wait-DurableTask（即 WhenAll）调用的结果列表中删除 Null 值。这意味着，成功调用不带 -Any 标志的 Wait-DurableTask 应该会返回一个与其计划的任务数大小相同的数组。

在何处获取支持、提供反馈和提出更改建议

在此版本的预览阶段，独立版 SDK 可能会引入更多更改。这些更改可能会受到社区的影响，因此请向 SDK 的新 GitHub 存储库报告任何反馈和建议。

通过