獨立式 Durable Functions PowerShell SDK 指南

Durable Functions （DF） PowerShell SDK 現在可作為 PowerShell 資源庫中的獨立模組使用： AzureFunctions.PowerShell.Durable.SDK。 此 SDK 現已 正式推出（GA）， 是使用 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 和之前的版本使用。

我們計劃最終要發行沒有內建 SDK 的全新 PowerShell 背景工作角色主要版本。 此時，使用者必須使用此獨立式套件個別安裝 SDK；安裝步驟如下所述。

安裝並啟用 SDK

請參閱本節，以了解如何在現有的應用程式中安裝和啟用新的獨立式 SDK。

先決條件

獨立式 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 中執行，請使用您選擇的工具執行下列步驟：

Azure CLI

分別將 <FUNCTION_APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為您的函數應用程式名稱和資源群組名稱。

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

Azure PowerShell

分別將 <FUNCTION_APP_NAME> 和 <RESOURCE_GROUP_NAME> 取代為您的函數應用程式名稱和資源群組名稱。

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

VS Code

1. 請確保您已安裝適用於 VS Code 的 Azure Functions 延伸模組
2. 按 F1 以開啟命令選擇區。 在命令選擇區中，搜尋並選取 Azure Functions: Add New Setting...。
3. 出現提示時，選擇您的訂用帳戶和函數應用程式
4. 針對名稱，輸入 ExternalDurablePowerShellSDK，然後按 Enter。
5. 針對值，輸入 "true"，然後按 Enter。

安裝和匯入 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 下載到該模組目錄，例如：

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

• Cmdlet Get-DurableTaskResult 現在只接受單一 Task 做為自變數，而不是接受 Tasks 清單。
• Cmdlet New-DurableRetryOptions 會重新命名為 New-DurableRetryPolicy （提供舊名稱的別名以提供回溯相容性）。

行為變更

• 使用 Wait-DurableTask 排程的活動所擲回的例外狀況 (如同在展開傳送/收合傳送模式中)，不再以無訊息方式忽略。 相反地，在例外狀況上，Cmdlet 會將該例外狀況傳播至協調器，以便由使用者程式代碼處理。
• Null 值不再從 Wait-DurableTask (即 WhenAll) 叫用的結果清單中卸除。 這表示不使用 -Any 旗標成功叫用的 Wait-DurableTask 應該會傳回與排程工作數相同大小的陣列。

取得支援並提供意見回饋

請向 SDK 的 GitHub 存放庫報告任何意見反應和建議。