Sdílet prostřednictvím

Průvodce samostatnou Durable Functions powershellovou sadou SDK

  • Článek

Sada PowerShell SDK Durable Functions (DF) je teď 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í Durable Functions aplikací pomocí PowerShellu. V tomto článku vysvětlujeme výhody této změny a změny, které 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 PowerShellu. Tento přístup s sebou přináší výhodu, že Durable Functions aplikace bylo možné vytvářet pro Azure Functions uživatele PowerShellu. Došlo však také k různým nedostatkům:

  • Nové funkce, opravy chyb a další změny závisely na četnosti vydávání pracovních procesů PowerShellu.
  • Vzhledem k povaze automatického upgradu pracovního procesu PowerShellu je potřeba, aby sada DF SDK při opravách chyb byla konzervativní, 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, byl 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 odstranit. Toto jsou výhody využití tohoto nového balíčku samostatné sady SDK:

  • Tato sada SDK obsahuje mnoho vysoce požadovaných vylepšení, jako je lepší zpracování výjimek a hodnot null a opravy serializace.
  • Verze balíčku je nezávislá na pracovním procesu PowerShellu. To umožňuje uživatelům začlenit nové funkce a opravy, jakmile budou k dispozici, a zároveň se vyhnout zásadním změnám automatických upgradů.
  • Logika přehrání je rychlejší a spolehlivější: používá stejný modul přehrává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 dostupná 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:

Vyjádření souhlasu se samostatnou SADOU DF SDK

Ke 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ž vynutí pracovní proces používat externí sadu SDK.

Pokud používáte Azure Functions Core Tools místně, měli byste toto nastavení přidat do souborulocal.settings.json. Pokud používáte azure, postupujte podle těchto kroků s nástrojem podle vašeho výběru:

Nahraďte <FUNCTION_APP_NAME> a <RESOURCE_GROUP_NAME> názvem vaší aplikace funkcí a skupiny prostředků v uvedeném pořadí.

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

Instalace a import sady SDK

Balíček SADY SDK můžete nainstalovat dvěma způsoby: můžete ho nainstalovat jako spravovanou závislost nebo jako vlastní modul. V této části popíšeme obě možnosti, ale je potřeba jenom jedna z nich.

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

Pokud chcete nainstalovat sadu SDK jako spravovanou závislost, budete muset postupovat podle pokynů ke spravovaným závislostem. Podrobnosti najdete v doprovodných materiálech. Stručně řečeno, nejprve se musíte ujistit, že obsahuje managedDependencyhost.json 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 záznam pro sadu DF SDK ve vašem requirements.psd1 souboru, jako 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ů k vytvoření složky modulů na úrovni aplikace. Nezapomeňte si projít výše uvedené dokumenty, kde najdete podrobnosti. Stručně řečeno, balíček sady SDK budete muset umístit do ".\Modules" adresáře umístěného v kořenovém adresáři vaší aplikace.

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

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

Import sady SDK

Posledním krokem je import sady SDK do relace kódu. Provedete to tak, že do souboru naimportujete profile.ps1 sadu PowerShell SDKImport-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop. Pokud byla vaše aplikace například vygenerovaná prostřednictvím šablon, profile.ps1 soubor může nakonec 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 jako obvykle prostřednictvím func host start terminálu, abyste mohli začít 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 používání nové sady SDK.

Nové rutiny cmdlets

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

Upravené rutiny cmdlets

  • Příkaz CmdLet Get-DurableTaskResult -Task <task> teď přijímá jako argument pouze jeden úkol, místo aby přijímal seznam úkolů.

Změny chování

  • Výjimky vyvolané aktivitami Wait-DurableTask naplánovanými pomocí (jako ve vzoru Fan-Out/Fan-In) už nejsou bezobslužně ignorovány. Místo toho cmdLet při výjimce rozšíří výjimku do orchestrátoru, aby ji mohl zpracovat uživatelský kód.
  • Hodnoty null se už ze seznamu Wait-DurableTask výsledků vyvolání (tj. Přivšechny) nezahodí. To znamená, že úspěšné vyvolání Wait-DurableTask bez příznaku -Any by mělo vrátit pole stejné velikosti jako počet úkolů, které naplánoval.

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

Během fáze 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ěné komunitou, takže ohlaste zpětnou vazbu a návrhy do nového úložiště Sady SDK na GitHubu.