Share via

Guide till fristående Durable Functions PowerShell SDK

  • Artikel

PowerShell SDK för Durable Functions (DF) är nu tillgängligt som ett fristående paket i PowerShell-galleriet: AzureFunctions.PowerShell.Durable.SDK. När det här SDK-paketet är allmänt tillgängligt är det det rekommenderade sättet att redigera 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 implementerar det här nya paketet.

Anteckning

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

Motivation bakom fristående SDK

Den tidigare DF SDK:en var inbyggd i PowerShell-språkarbetaren. Den här metoden medförde 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 konservativt när det gäller att åtgärda buggar eftersom eventuella beteendeändringar kan utgöra en icke-bakåtkompatibel ändring.
  • Replay-algoritmen som används av den inbyggda DF SDK:en var inaktuell: 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:

  • Detta SDK innehåller många mycket begärda förbättringar, till exempel bättre hantering av undantag och null-värden och 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.
  • Replay-logiken är snabbare och mer tillförlitlig: den använder samma replay-motor som DF isolerad SDK för C#.

Utfasningsplan för det 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 en ny fristående SDK i din befintliga app.

Förutsättningar

Fristående PowerShell SDK kräver följande lägsta versioner:

Anmäl dig till fristående DF SDK

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 version 7.2 och senare, vilket tvingar arbetaren att använda den 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 dessa steg med valfritt verktyg:

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 som ett hanterat beroende eller som en anpassad modul. 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 riktlinjerna för hanterade beroenden. Mer information finns i vägledningen. Sammanfattningsvis måste du först se till att innehåller host.json 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 anvisningarna för att skapa en modulmapp på appnivå. 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.

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

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 filen profile.ps1 . Om din app till exempel har autogenererats via mallar profile.ps1 kan det hända att filen ser 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 som du kan förvänta dig när du använder den 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.

CmdLetar har ändrats

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

Beteendeändringar

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

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

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