独立版 Durable Functions PowerShell SDK 指南

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 需要以下最低版本:

选择加入独立版 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"

安装和导入 SDK

有两个用于安装 SDK 包的选项:它可以作为托管依赖项安装,也可以作为自定义模块进行安装。 在本部分,我们将介绍这两个选项,但只需要其中一个选项。

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

若要将 SDK 作为托管依赖项进行安装,需要遵循托管依赖项指南。 请查看指南了解详细信息。 总之,首先需要确保 host.json 包含 enabled 属性设置为 truemanagedDependency 部分。 下面是满足此要求的示例 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 存储库报告任何反馈和建议。