Průvodce samostatnou sadou SDK PowerShellu Durable Functions

Článek
01/23/2025

Sada PowerShell SDK Durable Functions (DF) je nyní dostupná ve verzi Preview jako samostatný balíček v Galerie prostředí PowerShell: AzureFunctions.PowerShell.Durable.SDK. Jakmile je tento balíček sady SDK obecně dostupný, bude doporučeným prostředkem vytváření aplikací Durable Functions pomocí PowerShellu. V tomto článku vysvětlujeme výhody této změny a jaké změny můžete očekávat při přijetí tohoto nového balíčku.

Poznámka:

Tento balíček je aktuálně ve verzi Preview.

Motivace za samostatnou sadou SDK

Předchozí sada DF SDK byla integrovaná do pracovního procesu jazyka PowerShell. Tento přístup přinesl výhodu, že aplikace Durable Functions můžou být vytvořené mimo tuto možnost pro uživatele Azure Functions PowerShellu. Došlo však také k různým nedostatkům:

Nové funkce, opravy chyb a další změny byly závislé na tempu vydávání pracovních procesů PowerShellu.
Vzhledem k povaze automatického upgradu pracovního procesu PowerShellu je potřeba, aby sada DF SDK byla konzervativní, aby opravil chyby, protože jakékoli změny chování by mohly představovat zásadní změnu.
Algoritmus přehrání, který využívá integrovaná sada DF SDK, byla zastaralá: jiné sady SDK DF už využívaly rychlejší a spolehlivější implementaci.

Vytvořením samostatného balíčku sady DF PowerShell SDK můžeme tyto nedostatky překonat. Toto jsou výhody využití tohoto nového samostatného balíčku SDK:

Tato sada SDK zahrnuje řadu vysoce požadovaných vylepšení, jako je lepší zpracování výjimek a zpracování hodnot null a opravy serializace.
Balíček se provádí nezávisle na pracovním procesu PowerShellu. To uživatelům umožňuje začlenit nové funkce a opravy, jakmile budou k dispozici, a zároveň se vyhnout zásadním změnám z automatických upgradů.
Logika přehrávání je rychlejší a spolehlivější: používá stejný modul pro přehrání jako izolovaná sada SDK DF pro C#.

Plán vyřazení integrované sady DF PowerShell SDK

Integrovaná sada DF SDK v pracovním procesu PowerShellu zůstane k dispozici pro PowerShell 7.4, 7.2 a předchozí verze.

Plánujeme nakonec vydat novou hlavní verzi pracovního procesu PowerShellu bez integrované sady SDK. V tomto okamžiku by uživatelé museli sadu SDK nainstalovat samostatně pomocí tohoto samostatného balíčku; Postup instalace je popsaný níže.

Instalace a povolení sady SDK

V této části se dozvíte, jak nainstalovat a povolit novou samostatnou sadu SDK ve stávající aplikaci.

Požadavky

Samostatná sada PowerShell SDK vyžaduje následující minimální verze:

Modul runtime Azure Functions verze 4.16 nebo novější
Azure Functions Core Tools v4.0.5095+ (pokud běží místně)
Aplikace PowerShell pro Azure Functions pro PowerShell 7.2 nebo novější

Přihlášení k samostatné DF SDK

K spuštění samostatné sady PowerShell SDK se vyžaduje následující nastavení aplikace:

Název: ExternalDurablePowerShellSDK
Hodnota: "true"

Toto nastavení aplikace zakáže integrovanou sadu Durable SDK pro PowerShell verze 7.2 a vyšší, což způsobí, že pracovní proces použije externí sadu SDK.

Pokud používáte Nástroje Azure Functions Core Tools místně, měli byste do local.settings.json souboru přidat toto nastavení. Pokud používáte v Azure, použijte tento postup s nástrojem podle svého výběru:

Nahraďte <FUNCTION_APP_NAME> a <RESOURCE_GROUP_NAME> nahraďte název vaší aplikace funkcí a skupiny prostředků.

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

Nahraďte <FUNCTION_APP_NAME> a <RESOURCE_GROUP_NAME> nahraďte název vaší aplikace funkcí a skupiny prostředků.

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

Instalace a import sady SDK

Máte dvě možnosti instalace balíčku SDK: můžete ho nainstalovat pomocí spravovaných závislostí nebo sbalit obsah aplikace. V této části popisujeme obě možnosti, ale potřebujeme jenom jednu z nich.

Možnost instalace 1: Použití spravovaných závislostí

Pokud chcete sadu SDK nainstalovat jako spravovanou závislost, budete muset postupovat podle pokynů ke spravovaným závislostem. Podrobnosti najdete v doprovodných materiálech. V souhrnu nejprve musíte zajistit host.json , aby obsahoval managedDependency oddíl s vlastností nastavenou enabled na true. Níže je příklad host.json , který splňuje tento požadavek:

{
  "version": "2.0",
  "managedDependency": {
    "enabled": true
  },
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.*, 4.0.0)"
  },
}

Pak stačí zadat položku pro sadu DF SDK ve vašem requirements.psd1 souboru, jak je znázorněno v následujícím příkladu:

# 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.*'
}

Možnost instalace 2: Použití vlastních modulů

Pokud chcete nainstalovat samostatnou sadu DF SDK jako vlastní modul, musíte postupovat podle pokynů týkajících se zahrnutí modulů do obsahu aplikace. Podrobnosti najdete v výše uvedených dokumentech. Stručně řečeno, budete muset balíček sady SDK umístit do ".\Modules" adresáře umístěného v kořenovém adresáři aplikace.

Například z kořenového adresáře vaší aplikace a po vytvoření ".\Modules" adresáře můžete stáhnout samostatnou sadu SDK do adresáře modulů, například:

Save-Module -Name AzureFunctions.PowerShell.Durable.SDK -AllowPrerelease -Path ".\Modules"

Import sady SDK

Posledním krokem je import sady SDK do relace kódu. Uděláte to tak, že do souboru profile.ps1 naimportujete sadu PowerShell SDKImport-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop. Pokud se vaše aplikace například vygenerovala prostřednictvím šablon, profile.ps1 může soubor vypadat takto:

# 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

Toto jsou všechny kroky potřebné k využití další sady PowerShell SDK. Spusťte aplikaci normálně, a to tak, že v func host start terminálu začnete používat sadu SDK.

Průvodce migrací

V této části popisujeme změny rozhraní a chování, které můžete očekávat při využití nové sady SDK.

Nové rutiny

Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> je nový CmdLet, který uživatelům umožňuje využívat suborchestrátory ve svých pracovních postupech.

Změněné rutiny

Příkaz CmdLet Get-DurableTaskResult -Task <task> teď přijímá pouze jeden úkol jako argument místo přijetí seznamu úkolů.

Změny chování

Výjimky vyvolané aktivitami Wait-DurableTask naplánovanými (jako ve vzoru Fan-Out/Fan-In) se už bezobslužně ignorují. Místo toho cmdLet na výjimku rozšíří výjimku do orchestrátoru, aby ji mohl zpracovat uživatelský kód.
Hodnoty null se už nezahazují ze seznamu Wait-DurableTask výsledků vyvolání (tj. WhenAll). To znamená, že úspěšné vyvolání Wait-DurableTask bez příznaku -Any by mělo vrátit pole se stejnou velikostí jako počet naplánovaných úkolů.

Kde získat podporu, poskytnout zpětnou vazbu a navrhnout změny

Ve fázi Preview této verze může samostatná sada SDK zavést několik dalších změn. Tyto změny můžou být ovlivněny komunitou, takže nahlašte jakékoli připomínky a návrhy do nového úložiště Sady SDK na GitHubu.

Sdílet prostřednictvím