Dela via

Guide till fristående Durable Functions PowerShell SDK

  • Artikel

Durable Functions (DF) PowerShell SDK är nu tillgängligt i förhandsversionen som ett fristående paket i PowerShell-galleriet: AzureFunctions.PowerShell.Durable.SDK. När det här SDK-paketet är GA är det det rekommenderade sättet att skapa Durable Functions-appar med PowerShell. I den här artikeln förklarar vi fördelarna med den här ändringen och vilka ändringar du kan förvänta dig när du använder det här nya paketet.

Kommentar

Det här paketet är för närvarande i förhandsversion.

Motivation bakom fristående SDK

Den tidigare DF SDK:en byggdes in i PowerShell-språkarbetaren. Den här metoden kom med fördelen att Durable Functions-appar kunde redigeras direkt för Azure Functions PowerShell-användare. Men det kom också med olika brister:

  • Nya funktioner, felkorrigeringar och andra ändringar var beroende av PowerShell-arbetarens lanseringstakt.
  • På grund av PowerShell-arbetarens automatiska uppgradering behövde DF SDK vara konservativ när det gäller att åtgärda buggar eftersom eventuella beteendeändringar kan utgöra en icke-bakåtkompatibel ändring.
  • Reprisalgoritmen som användes av den inbyggda DF SDK:en var föråldrad: andra DF SDK:er använde redan en snabbare och mer tillförlitlig implementering.

Genom att skapa ett fristående DF PowerShell SDK-paket kan vi lösa dessa brister. Det här är fördelarna med att använda det här nya fristående SDK-paketet:

  • Det här SDK:t innehåller många mycket efterfrågade förbättringar, till exempel bättre undantags- och null-värdehantering samt serialiseringskorrigeringar.
  • Paketet är versionshanterat oberoende av PowerShell-arbetaren. Detta gör det möjligt för användare att införliva nya funktioner och korrigeringar så snart de är tillgängliga, samtidigt som de undviker icke-bakåtkompatibla ändringar från automatiska uppgraderingar.
  • Uppspelningslogiken är snabbare och mer tillförlitlig: den använder samma reprismotor som DF-isolerad SDK för C#.

Utfasningsplan för den inbyggda DF PowerShell SDK

Den inbyggda DF SDK:t i PowerShell-arbetaren förblir tillgänglig för PowerShell 7.4, 7.2 och tidigare versioner.

Vi planerar att så småningom släppa en ny huvudversion av PowerShell-arbetaren utan den inbyggda SDK:n. Då skulle användarna behöva installera SDK:et separat med det här fristående paketet. installationsstegen beskrivs nedan.

Installera och aktivera SDK

Se det här avsnittet om du vill lära dig hur du installerar och aktiverar ny fristående SDK i din befintliga app.

Förutsättningar

Den fristående PowerShell SDK:en kräver följande lägsta versioner:

Anmäl dig till det fristående DF SDK:et

Följande programinställning krävs för att köra fristående PowerShell SDK:

  • Namn: ExternalDurablePowerShellSDK
  • Värde: "true"

Den här programinställningen inaktiverar den inbyggda Durable SDK för PowerShell-versionerna 7.2 och senare, vilket tvingar arbetaren att använda det externa SDK:t.

Om du kör lokalt med Azure Functions Core Tools bör du lägga till den här inställningen i local.settings.json filen. Om du kör i Azure följer du de här stegen med det verktyg du väljer:

Ersätt <FUNCTION_APP_NAME> och <RESOURCE_GROUP_NAME> med namnet på din funktionsapp respektive resursgrupp.

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

Installera och importera SDK:n

Du har två alternativ för att installera SDK-paketet: det kan installeras med hanterade beroenden eller paketeras med ditt appinnehåll. I det här avsnittet beskriver vi båda alternativen, men bara ett av dem behövs.

Installationsalternativ 1: Använd hanterade beroenden

Om du vill installera SDK:t som ett hanterat beroende måste du följa vägledningen för hanterade beroenden. Mer information finns i vägledningen. Sammanfattningsvis måste du först se till att ditt host.json innehåller ett managedDependency avsnitt med en enabled egenskap inställd på true. Nedan visas ett exempel host.json som uppfyller detta krav:

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

Sedan behöver du bara ange en post för DF SDK i requirements.psd1 filen, som i exemplet nedan:

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

Installationsalternativ 2: Använd anpassade moduler

Om du vill installera fristående DF SDK som en anpassad modul måste du följa riktlinjerna för att inkludera moduler i appinnehåll. Se till att granska ovan nämnda dokument för mer information. Sammanfattningsvis måste du placera SDK-paketet i en ".\Modules" katalog som finns i appens rot.

Du kan till exempel ladda ned det fristående SDK:t till modulkatalogen från programmets rot och när du har skapat en ".\Modules" katalog:

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

Importera SDK:n

Det sista steget är att importera SDK:n till kodens session. Det gör du genom att importera PowerShell SDK via Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop i profile.ps1 filen. Om din app till exempel har kodats via mallar kan filen profile.ps1 se ut så här:

# 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

Det här är alla steg som krävs för att använda nästa PowerShell SDK. Kör appen som vanligt via func host start i terminalen för att börja använda SDK:t.

Migreringsguide

I det här avsnittet beskriver vi de gränssnitts- och beteendeändringar du kan förvänta dig när du använder det nya SDK:n.

Nya cmdLetar

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> är en ny CmdLet som gör det möjligt för användare att använda suborchestratorer i sina arbetsflöden.

Ändrade cmdLetar

  • CmdLet Get-DurableTaskResult -Task <task> accepterar nu bara en enskild uppgift som argument, i stället för att acceptera en lista med uppgifter.

Förändringar i beteende

  • Undantag som genereras av aktiviteter som schemalagts med Wait-DurableTask (som i mönstret-Out/-In) ignoreras inte längre tyst. I stället sprids det undantaget till orkestratorn med hjälp av ett undantag, så att det kan hanteras av användarkod.
  • Null-värden tas inte längre bort från resultatlistan för ett Wait-DurableTask (t.ex. WhenAll)-anrop. Det innebär att ett lyckat anrop utan Wait-DurableTask -Any flaggan ska returnera en matris med samma storlek som antalet aktiviteter som den schemalagt.

Var du kan få support, ge feedback och föreslå ändringar

Under förhandsversionen av den här versionen kan det fristående SDK:et introducera några fler ändringar. Dessa ändringar kan påverkas av communityn så rapportera eventuell feedback och förslag till SDK:ns nya GitHub-lagringsplats.