Handleiding voor de zelfstandige Durable Functions PowerShell SDK

Artikel
01/23/2025

De PowerShell SDK (Durable Functions) (DF) is nu beschikbaar als preview-versie als zelfstandig pakket in de PowerShell Gallery: AzureFunctions.PowerShell.Durable.SDK. Zodra dit SDK-pakket algemeen beschikbaar is, is dit de aanbevolen oplossing 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 beschikbaar als preview-versie.

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, 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 om de zelfstandige PowerShell SDK uit te voeren:

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 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 <RESOURCE_GROUP_NAME> door <FUNCTION_APP_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"

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

Update-AzFunctionAppSetting -Name <FUNCTION_APP_NAME> -ResourceGroupName <RESOURCE_GROUP_NAME> -AppSetting @{"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' = '1.*'
}

Installatieoptie 2: Aangepaste modules gebruiken

Als u de zelfstandige DF SDK wilt installeren als een aangepaste module, 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.

Migratiehandleiding

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

Nieuwe cmdlets

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

Gewijzigde cmdLets

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

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 deze uitzondering door de CmdLet op een uitzondering doorgegeven 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 (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.

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 introduceren. Deze wijzigingen kunnen worden beïnvloed door de community, zodat u feedback en suggesties kunt rapporteren aan de nieuwe GitHub-opslagplaats van de SDK.

Delen via