Handleiding voor de zelfstandige Durable Functions PowerShell SDK

De Durable Functions (DF) PowerShell SDK is nu beschikbaar in preview als een zelfstandig pakket in de PowerShell Gallery: AzureFunctions.PowerShell.Durable.SDK. Zodra dit SDK-pakket algemeen beschikbaar is, wordt het de aanbevolen methode voor het ontwerpen van Durable Functions apps met PowerShell. In dit artikel leggen we de voordelen van deze wijziging uit en welke wijzigingen u kunt verwachten wanneer u dit nieuwe pakket in gebruik neemt.

Notitie

Dit pakket is momenteel in preview.

Motivatie achter de zelfstandige SDK

De vorige DF SDK is ingebouwd in de PowerShell-taalwerkrol. Deze aanpak heeft als voordeel dat Durable Functions apps direct kunnen worden gemaakt voor Azure Functions PowerShell-gebruikers. Het kwam echter ook met verschillende tekortkomingen:

• Nieuwe functies, oplossingen voor fouten en andere wijzigingen waren afhankelijk van de releasefrequentie van de PowerShell-werkrol.
• Vanwege de aard van het automatisch upgraden van de PowerShell-werkrol, moest de DF SDK voorzichtig zijn met het oplossen van fouten, omdat eventuele gedragswijzigingen een wijziging kunnen zijn die fouten veroorzaakt.
• Het replay-algoritme dat door de ingebouwde DF SDK wordt gebruikt, is verouderd: andere DF SDK's maakten al gebruik van een snellere en betrouwbaardere implementatie.

Door een zelfstandig DF PowerShell SDK-pakket te maken, kunnen we deze tekortkomingen oplossen. Dit zijn de voordelen van het gebruik van dit nieuwe zelfstandige SDK-pakket:

• Deze SDK bevat veel veel aangevraagde verbeteringen, zoals betere verwerking van uitzonderingen en null-waarde en serialisatiecorrecties.
• De versie van het pakket is onafhankelijk van de PowerShell-werkrol. Hiermee kunnen gebruikers nieuwe functies en oplossingen opnemen zodra ze beschikbaar zijn, terwijl ook wordt voorkomen dat wijzigingen die fouten veroorzaken door automatische upgrades.
• De logica voor opnieuw afspelen is sneller en betrouwbaarder: deze maakt gebruik van dezelfde replay-engine als de geïsoleerde DF-SDK voor C#.

Afschaffingsplan voor de ingebouwde DF PowerShell SDK

De ingebouwde DF SDK in de PowerShell-werkrol blijft beschikbaar voor PowerShell 7.4, 7.2 en eerdere versies.

We zijn van plan om uiteindelijk een nieuwe primaire versie van de PowerShell-werkrol uit te brengen zonder de ingebouwde SDK. Op dat moment moeten gebruikers de SDK afzonderlijk installeren met behulp van dit zelfstandige pakket; de installatiestappen worden hieronder beschreven.

De SDK installeren en inschakelen

Zie deze sectie voor meer informatie over het installeren en inschakelen van een nieuwe zelfstandige SDK in uw bestaande app.

Vereisten

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.2 of hoger

Aanmelden voor de zelfstandige DF SDK

De volgende toepassingsinstelling is vereist voor het uitvoeren van de zelfstandige PowerShell SDK:

• Naam: ExternalDurablePowerShellSDK
• Waarde: "true"

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

Als u lokaal werkt met Azure Functions Core Tools, 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:

Azure-CLI

Vervang respectievelijk en <RESOURCE_GROUP_NAME> door <FUNCTION_APP_NAME> de naam van uw functie-app en resourcegroep.

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

Azure PowerShell

Vervang respectievelijk en <RESOURCE_GROUP_NAME> door <FUNCTION_APP_NAME> de naam van uw functie-app en resourcegroep.

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

VS-code

1. Zorg ervoor dat u de Azure Functions-extensie voor VS Code hebt geïnstalleerd
2. Druk op F1 om het opdrachtenpalet te openen. In het opdrachtenpalet zoekt en selecteert u Azure Functions: Add New Setting....
3. Kies uw abonnement en functie-app wanneer u hierom wordt gevraagd
4. Typ voor de naam ExternalDurablePowerShellSDK en druk op Enter.
5. Typ voor de waarde "true" en druk op Enter.

De SDK installeren en importeren

U hebt twee opties voor het installeren van het SDK-pakket: het kan worden geïnstalleerd als een beheerde afhankelijkheid of als een aangepaste module. In deze sectie beschrijven we beide opties, maar er is slechts één van de opties nodig.

Installatieoptie 1: Beheerde afhankelijkheden gebruiken

Als u de SDK wilt installeren als een beheerde afhankelijkheid, moet u de richtlijnen voor beheerde afhankelijkheden volgen. Raadpleeg de richtlijnen voor meer informatie. Samengevat moet u er eerst voor zorgen dat uw host.json sectie een managedDependency sectie bevat met een enabled eigenschap die is ingesteld op true. Hieronder ziet u een voorbeeld host.json dat aan deze vereiste voldoet:

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

Vervolgens hoeft u alleen maar een vermelding op te geven voor de DF SDK in uw requirements.psd1 bestand, zoals in het onderstaande voorbeeld:

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

Installatieoptie 2: Aangepaste modules gebruiken

Als u de zelfstandige DF SDK als aangepaste module wilt installeren, moet u de richtlijnen volgen voor het maken van een map met modules op app-niveau. Lees de bovengenoemde documenten voor meer informatie. Kortom, u moet het SDK-pakket in een ".\Modules" map in de hoofdmap van uw app plaatsen.

U kunt bijvoorbeeld vanuit de hoofdmap van uw toepassing en na het maken van een ".\Modules" map de zelfstandige SDK als volgt downloaden naar de map van de modules:

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

De SDK importeren

De laatste stap is het importeren van de SDK in de sessie van uw code. Hiervoor importeert u de PowerShell SDK via Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop in uw profile.ps1 bestand. Als uw app bijvoorbeeld via sjablonen is gefingeerd, kan uw profile.ps1 bestand er als volgt uitzien:

# 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

Dit zijn alle stappen die nodig zijn om de volgende PowerShell-SDK te gebruiken. Voer uw app op de normale wijze uit, via func host start in uw terminal om de SDK te gaan gebruiken.

Migratiehandleiding

In deze sectie beschrijven we de interface- en gedragswijzigingen die u kunt verwachten bij het gebruik van de nieuwe SDK.

Nieuwe cmdlets

• Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> is een nieuwe CmdLet waarmee gebruikers suborchestrators kunnen gebruiken in hun werkstromen.

Gewijzigde cmdlets

• De CmdLet Get-DurableTaskResult -Task <task> accepteert nu slechts één taak als argument, in plaats van een lijst met taken.

Gedragswijzigingen

• Uitzonderingen die worden veroorzaakt door activiteiten die zijn gepland met Wait-DurableTask (zoals in het patroon Fan-Out/Fan-In) worden niet langer op de achtergrond genegeerd. In plaats daarvan geeft de CmdLet bij een uitzondering die uitzondering door aan de orchestrator, zodat deze kan worden verwerkt door gebruikerscode.
• Null-waarden worden niet meer verwijderd uit de lijst met resultaten van een Wait-DurableTask aanroep (dat wil zeggen WhenAll). Dit betekent dat een geslaagde aanroep van Wait-DurableTask zonder de -Any vlag een matrix moet retourneren van dezelfde grootte als het aantal taken dat is gepland.

Waar u ondersteuning kunt krijgen, feedback kunt geven en wijzigingen kunt voorstellen

Tijdens de preview-fase van deze release kan de zelfstandige SDK nog enkele wijzigingen aanbrengen. Deze wijzigingen kunnen worden beïnvloed door de community, dus meld feedback en suggesties aan de nieuwe GitHub-opslagplaats van de SDK.