Guide till fristående Durable Functions PowerShell SDK

Den fristående Durable Functions PowerShell SDK (AzureFunctions.PowerShell.Durable.SDK) är den rekommenderade metoden för att redigera Durable Functions appar med PowerShell. Den ersätter den inbyggda SDK:n med snabbare omspelningslogik (samma motor som C#-isolerad SDK), oberoende versionshantering och förbättrad undantagshantering, null-värdehantering och serialisering. Det inbyggda SDK:t är fortfarande tillgängligt för PowerShell 7.4 och tidigare, men tas bort i en framtida större version av PowerShell-arbetaren.

Checklista för migrering

Använd följande checklista för att spåra förloppet genom varje migreringssteg:

Installera fristående SDK

Följ de här stegen för att installera och aktivera det fristående SDK:et i din befintliga app.

Verifiera förutsättningar

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

• Azure Functions Runtime v4.16+
• Azure Functions Core Tools v4.0.5095+ (om det körs lokalt)
• Azure Functions PowerShell-app för PowerShell 7.4 eller senare

Aktivera fristående 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-versionerna 7.4 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:

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

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

Installera SDK-paketet

Du har två alternativ för att installera SDK-paketet. Använd hanterade beroenden (rekommenderas för de flesta appar) eller paketera modulen med ditt appinnehåll om du behöver fästa en viss version eller om distributionen inte stöder hanterade beroenden. Endast ett alternativ behövs.

Alternativ 1: Använd hanterade beroenden (rekommenderas)

Om du vill installera SDK:t som ett hanterat beroende följer du vägledningen för hanterade beroenden. Kontrollera först att ditt host.json innehåller ett managedDependency avsnitt med enabled inställt på true:

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

Ange sedan en post för SDK:t i requirements.psd1 filen:

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

Alternativ 2: Inkludera SDK-modulen i appinnehållet

Om du vill paketera SDK:et med din app placerar du SDK-paketet i en ".\Modules" katalog i appens rot. Mer information finns i Inkludera moduler i appinnehåll.

Skapa katalogen från programroten och ladda ned SDK:et:

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

Importera SDK:n

Lägg till följande rad i profile.ps1 filen för att importera SDK:n vid varje kallstart:

Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Kör din app

Starta appen med func host start. Det fristående SDK:et är nu aktivt.

Migrera från det inbyggda SDK:et

Om du migrerar en befintlig app från den inbyggda SDK:en granskar du följande gränssnitt och beteendeändringar.

Nya cmdlets

Ändrade cmdlets

Förändringar i beteende

Undantagshantering i Wait-DurableTask

Undantag som genereras av aktiviteter som schemalagts med Wait-DurableTask (fan-out/fan-in-mönster) ignoreras inte tyst längre. Cmdleten sprider nu undantaget till orchestrator så att du kan hantera det i koden.

Inbyggd SDK – undantagen svaldes tyst:

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

Fristående SDK – undantag sprids till orkestrator:

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Null-värden bevaras i Wait-DurableTask resultat

Null-värden tas inte längre bort från resultatlistan för ett Wait-DurableTask (WhenAll)-anrop. Ett lyckat anrop utan -Any flaggan returnerar nu en matris med samma storlek som antalet schemalagda aktiviteter, inklusive $null poster för aktiviteter som returnerade null.

Inbyggd SDK – nullresultat togs bort:

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

Fristående SDK – nullresultat bevaras:

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

SDK-referens

Fullständig cmdlet-referens finns i AzureFunctions.PowerShell.Durable.SDK Module. När du har importerat modulen kan du också köra Get-Help *-Durable* för att visa en lista över alla tillgängliga cmdletar eller Get-Help <cmdlet-name> -Full för detaljerad användning.

Få support

Rapportera buggar och funktionsbegäranden i SDK:ts GitHub lagringsplats.

Nästa steg

• Skapa en Durable Functions app med PowerShell
• Mönster och begrepp för Durable Functions
• PowerShell-utvecklarreferens för Azure Functions