Handleiding voor de zelfstandige Durable Functions PowerShell SDK

De zelfstandige Durable Functions PowerShell SDK (AzureFunctions.PowerShell.Durable.SDK) is de aanbevolen methode voor het ontwerpen van Durable Functions apps met PowerShell. Deze vervangt de ingebouwde SDK door snellere logica voor opnieuw afspelen (dezelfde engine als de geïsoleerde C#-SDK), onafhankelijke versiebeheer en verbeterde verwerking van uitzonderingen, verwerking van null-waarden en serialisatie. De ingebouwde SDK blijft beschikbaar voor PowerShell 7.4 en eerder, maar wordt verwijderd in een toekomstige grote versie van de PowerShell-werkrol.

Controlelijst voor migratie

Gebruik de volgende controlelijst om de voortgang van elke migratiestap bij te houden:

De zelfstandige SDK installeren

Volg deze stappen om de zelfstandige SDK in uw bestaande app te installeren en in te schakelen.

Controleer de vereisten vooraf

Voor de zelfstandige PowerShell SDK zijn de volgende minimale versies vereist:

• Azure Functions Runtime v4.16+
• Azure Functions Core Tools v4.0.5095+ (indien lokaal uitgevoerd)
• Azure Functions PowerShell-app voor PowerShell 7.4 of hoger

De zelfstandige SDK inschakelen

De volgende toepassingsinstelling is vereist om de zelfstandige PowerShell SDK uit te voeren:

• Naam: ExternalDurablePowerShellSDK
• Waarde: "true"

Met deze toepassingsinstelling wordt de ingebouwde Durable SDK voor PowerShell-versies 7.4 en hoger uitgeschakeld, waardoor de werkrol de externe SDK moet gebruiken.

Als u lokaal werkt met behulp van de Core Tools van Azure Functions, moet u deze instelling toevoegen aan uw local.settings.json-bestand. Als u in Azure werkt, volgt u deze stappen met het hulpprogramma van uw keuze:

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'"}

Het SDK-pakket installeren

U hebt twee opties voor het installeren van het SDK-pakket. Gebruik beheerde afhankelijkheden (aanbevolen voor de meeste apps) of bundel de module met uw app-inhoud als u een specifieke versie moet vastmaken of als uw implementatie beheerde afhankelijkheden niet ondersteunt. Er is slechts één optie nodig.

Optie 1: Beheerde afhankelijkheden gebruiken (aanbevolen)

Als u de SDK wilt installeren als een beheerde afhankelijkheid, volgt u de richtlijnen voor beheerde afhankelijkheden. Controleer eerst of uw host.json een managedDependency-gedeelte bevat met enabled ingesteld op true.

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

Geef vervolgens een vermelding op voor de SDK in uw requirements.psd1 bestand:

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

Optie 2: de SDK-module opnemen in de app-inhoud

Als u de SDK wilt bundelen met uw app, plaatst u het SDK-pakket in een ".\Modules" map in de hoofdmap van uw app. Zie Het opnemen van modules in app-inhoud voor meer informatie.

Maak vanuit de hoofdmap van uw toepassing een nieuwe directory en download de SDK.

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

De SDK importeren

Voeg de volgende regel toe aan uw profile.ps1 bestand om de SDK bij elke koude start te importeren:

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

Uw app uitvoeren

Start uw app met func host start. De zelfstandige SDK is nu actief.

Migreren vanuit de ingebouwde SDK

Als u een bestaande app migreert vanuit de ingebouwde SDK, controleert u de volgende interface en gedragswijzigingen.

Nieuwe cmdlets

Gewijzigde cmdlets

Gedragswijzigingen

Afhandeling van uitzonderingen in Wait-DurableTask

Uitzonderingen die worden gegenereerd door activiteiten die zijn gepland met Wait-DurableTask (fan-out/fan-in patroon) worden niet meer stilletjes genegeerd. De cmdlet heeft nu de uitzondering doorgegeven aan de orchestrator, zodat u deze in uw code kunt afhandelen.

Ingebouwde SDK : uitzonderingen werden op de achtergrond ingeslikt:

# 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

Zelfstandige SDK : uitzonderingen worden doorgegeven aan de orchestrator:

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-waarden behouden in Wait-DurableTask resultaten

Null-waarden worden niet meer verwijderd uit de lijst met resultaten van een Wait-DurableTask aanroep (WhenAll). Een geslaagde aanroep zonder de -Any vlag retourneert nu een matrix van dezelfde grootte als het aantal geplande taken, inclusief $null vermeldingen voor activiteiten die null hebben geretourneerd.

Ingebouwde SDK: null-resultaten zijn verwijderd:

# 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

Zelfstandige SDK : null-resultaten blijven behouden:

# 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-referentie

Zie AzureFunctions.PowerShell.Durable.SDK-module voor de volledige naslaginformatie over cmdlets. Nadat u de module hebt geïmporteerd, kunt u ook uitvoeren Get-Help *-Durable* om alle beschikbare cmdlets of Get-Help <cmdlet-name> -Full voor gedetailleerd gebruik weer te geven.

Ondersteuning vinden

Fouten en functieaanvragen rapporteren in de GitHub-opslagplaats van de SDK.

Volgende stappen 

• Maak een Durable Functions-app met PowerShell
• Durable Functions-patronen en -concepten
• PowerShell-ontwikkelaarsreferenties voor Azure Functions