Sdílet prostřednictvím

Průvodce samostatnou sadou SDK PowerShellu Durable Functions

PowerShell SDK pro Durable Functions je nyní k dispozici jako samostatný modul v galerii PowerShell: AzureFunctions.PowerShell.Durable.SDK. Tato sada SDK je teď obecně dostupná (GA) a je doporučeným přístupem k 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.

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 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:

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.4 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"

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

Možnost instalace 2: Zahrnutí modulu SDK do obsahu aplikace

Pokud chcete do obsahu aplikace zahrnout samostatnou sadu DF SDK, 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 Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop naimportujete sadu PowerShell SDKprofile.ps1. 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.

Referenční příručka SDK

Kompletní referenční informace o rutinách sady SDK a jejich parametrech najdete v modulu AzureFunctions.PowerShell.Durable.SDK .

Pomocí cmdletu Get-Help můžete také získat podrobné popisy cmdletů sady SDK. Abyste to mohli udělat, musíte nejprve importovat modul, jak je znázorněno v předchozí části. Potom můžete spuštěním následujícího příkazu získat celý seznam rutin:

Get-Help *-Durable*

Pokud chcete získat podrobnou nápovědu ke konkrétní rutině, včetně příkladů použití, spusťte:

Get-Help Invoke-DurableOrchestration -Full

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 je nový cmdlet, který uživatelům umožňuje využívat suborchestrátory ve svých pracovních proudech.
  • Suspend-DurableOrchestration a Resume-DurableOrchestration jsou to nové rutiny, které uživatelům umožňují pozastavit a obnovit orchestraci.

Upravené rutiny

  • Rutina Get-DurableTaskResult teď přijímá pouze jeden úkol jako argument místo přijetí seznamu úkolů.
  • Cmdlet New-DurableRetryOptions se přejmenuje na New-DurableRetryPolicy (pro starý název je poskytován alias kvůli zpětné kompatibilitě).

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í. Namísto toho při výjimce se tato výjimka předá 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ů.

Získejte podporu a poskytněte zpětnou vazbu

Ohlaste nám prosím zpětnou vazbu a návrhy do úložiště GitHub sady SDK.