獨立式 Durable Functions PowerShell SDK 指南

發行項
03/18/2024

Durable Functions (DF) PowerShell SDK 現已開放使用 (預覽版)，作為 PowerShell 資源庫中的獨立套件：AzureFunctions.PowerShell.Durable.SDK。一旦此 SDK 套件正式發行，即建議採用此套件來使用 PowerShell 撰寫 Durable Functions 應用程式。本文說明這項變更的優點，以及採用這個新套件時可預期的變更。

注意

此套件目前為預覽狀態。

獨立式 SDK 背後的動機

先前的 DF SDK 是內建於 PowerShell 語言背景工作角色中。這種方法的優點是，Azure Functions PowerShell 使用者可以立即撰寫 Durable Functions 應用程式。但也有各種缺點：

新功能、錯誤修正程式和其他變更與 PowerShell 背景工作角色的發行頻率息息相關。
由於 PowerShell 背景工作角色的自動升級本質，DF SDK 必須對錯誤修正採取謹慎態度，因為任何行為變更都可能會造成中斷性變更。
內建 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 和之前的版本使用。

我們計劃最終要發行沒有內建 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版和更新版本的內建 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' = '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 會將該例外狀況傳播至協調器，以便由使用者程式碼處理。
Null 值不再從 Wait-DurableTask (即 WhenAll) 叫用的結果清單中卸除。這表示不使用 -Any 旗標成功叫用的 Wait-DurableTask 應該會傳回與排程工作數相同大小的陣列。

取得支援的位置、提供意見反應和建議變更

在此版本的預覽階段，獨立式 SDK 可能會再加入一些變更。這些變更可能會受到社群的影響，因此請向 SDK 的新 GitHub 存放庫回報任何意見反應和建議。