Delen via

Handleiding voor de zelfstandige Durable Functions PowerShell SDK

De Durable Functions (DF) PowerShell SDK is nu beschikbaar als een zelfstandige module in de PowerShell Gallery: AzureFunctions.PowerShell.Durable.SDK. Deze SDK is nu algemeen beschikbaar (GA) en is de aanbevolen benadering 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.

Motivatie achter de zelfstandige SDK

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

  • Nieuwe functies, bugfixes en andere wijzigingen waren afhankelijk van de releasefrequentie van de PowerShell-werkrol.
  • Vanwege de aard van de automatische upgrade van de PowerShell-werkrol moest de DF SDK conservatief zijn om bugs op te lossen, omdat eventuele gedragswijzigingen een belangrijke wijziging kunnen vormen.
  • Het herhalingsalgoritmen die door de ingebouwde DF SDK worden gebruikt, zijn verouderd: andere DF SDK's hebben al een snellere en betrouwbaardere implementatie gebruikt.

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 verwerking van null-waarden en serialisatieoplossingen.
  • Het pakket wordt onafhankelijk van de PowerShell-werkrol geversied. Hierdoor kunnen gebruikers nieuwe functies en oplossingen opnemen zodra ze beschikbaar zijn, terwijl ze ook voorkomen dat wijzigingen van automatische upgrades worden onderbroken.
  • De logica voor opnieuw afspelen is sneller en betrouwbaarder: deze maakt gebruik van dezelfde herhalingsengine 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 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:

Aanmelden voor de zelfstandige DF SDK

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 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:

Vervang en <FUNCTION_APP_NAME> door <RESOURCE_GROUP_NAME> respectievelijk 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"

De SDK installeren en importeren

U hebt twee opties voor het installeren van het SDK-pakket: het kan worden geïnstalleerd met beheerde afhankelijkheden of gebundeld met uw app-inhoud. In deze sectie beschrijven we beide opties, maar er is slechts één van deze 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. Kortom, u moet eerst controleren of uw host.json sectie een managedDependency sectie bevat waarop een enabled eigenschap is ingesteld.true Hieronder ziet u een voorbeeld host.json dat voldoet aan deze vereiste:

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

Vervolgens hoeft u alleen 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' = '2.*'
}

Installatieoptie 2: de SDK-module opnemen in uw app-inhoud

Als u de zelfstandige DF SDK in uw app-inhoud wilt opnemen, moet u de richtlijnen volgen met betrekking tot het opnemen van modules in app-inhoud. Controleer 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 downloaden naar de map met modules, zoals:

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 uw profile.ps1 bestand. Als uw app bijvoorbeeld is voorbereid via sjablonen, 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 als normaal uit via func host start uw terminal om de SDK te gaan gebruiken.

SDK-referentie

Zie de Module AzureFunctions.PowerShell.Durable.SDK voor de volledige naslaginformatie over de SDK-cmdlets en de bijbehorende parameters.

U kunt de Get-Help cmdlet ook gebruiken om gedetailleerde beschrijvingen van de SDK-cmdlets op te halen. Hiervoor moet u eerst de module importeren, zoals wordt weergegeven in de vorige sectie. Daarna kunt u de volgende opdracht uitvoeren om de volledige lijst met cmdlets op te halen:

Get-Help *-Durable*

Voer de volgende opdracht uit om gedetailleerde hulp te krijgen bij een specifieke cmdlet, inclusief gebruiksvoorbeelden:

Get-Help Invoke-DurableOrchestration -Full

Migratiehandleiding

In deze sectie beschrijven we de interface- en gedragswijzigingen die u kunt verwachten wanneer u de nieuwe SDK gebruikt.

Nieuwe cmdLets

  • Invoke-DurableSubOrchestrator is een nieuwe cmdlet waarmee gebruikers suborchestrators in hun werkstromen kunnen gebruiken.
  • Suspend-DurableOrchestration en Resume-DurableOrchestration zijn nieuwe cmdlets waarmee gebruikers respectievelijk orkestraties kunnen onderbreken en hervatten.

Gewijzigde cmdlets

  • De Get-DurableTaskResult cmdlet accepteert nu slechts één taak als argument, in plaats van een lijst met taken te accepteren.
  • De naam van de New-DurableRetryOptions cmdlet wordt gewijzigd New-DurableRetryPolicy in (er wordt een alias voor de oude naam opgegeven voor compatibiliteit met eerdere versies).

Gedragswijzigingen

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

Ontvang ondersteuning en geef feedback

Meld eventuele feedback en suggesties aan de GitHub-opslagplaats van de SDK.