分享方式:


獨立式 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 應用程式。 但也有各種缺點:

  • 新功能、錯誤修正程式和其他變更與 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 需要下列最低版本:

選擇使用獨立式 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"

安裝和匯入 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 存放庫回報任何意見反應和建議。