獨立式 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 需要下列最低版本:
- 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"
安裝和匯入 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 存放庫回報任何意見反應和建議。