Leitfaden zum eigenständigen Durable Functions PowerShell SDK

Artikel
06/12/2023

Das Durable Functions (DF) PowerShell SDK ist jetzt in der Vorschauversion als eigenständiges Paket im PowerShell-Katalog verfügbar: AzureFunctions.PowerShell.Durable.SDK. Sobald dieses SDK-Paket allgemein verfügbar ist, wird empfohlen, Durable Functions-Anwendungen mit PowerShell zu erstellen. In diesem Artikel erläutern wir die Vorteile dieser Änderung sowie welche Änderungen Sie durch die Einführung dieses neuen Pakets erwarten können.

Hinweis

Dieses Paket befindet sich derzeit in der Vorschauversion.

Motive für das eigenständige SDK

Das vorherige DF SDK war in den PowerShell-Sprachworker integriert. Dieser Ansatz hatte den Vorteil, dass sofort einsatzbereite Durable Functions-Anwendungen für Azure Functions PowerShell-Benutzer erstellt werden konnten. Es gab dabei jedoch auch verschiedene Einschränkungen:

Neue Features, Fehlerbehebungen und andere Änderungen waren vom Releaserhythmus des PowerShell-Workers abhängig.
Aufgrund der automatischen Aktualisierung des PowerShell-Workers musste das DF SDK beim Beheben von Fehlern konservativ ausgelegt sein, da jeder Behavior Change eine Breaking Change darstellen konnte.
Der vom integrierten DF SDK verwendete Wiedergabealgorithmus war veraltet: Andere DF SDKs verwendeten bereits eine schnellere und zuverlässigere Implementierung.

Durch das Erstellen eines eigenständigen DF PowerShell SDK-Pakets beheben wir diese Mängel Einschränkungen. Sie haben folgende Vorteile, wenn Sie dieses neue eigenständige SDK-Paket verwenden:

Dieses SDK enthält viele dringend geforderte Verbesserungen wie eine bessere Ausnahme- und NULL-Wert-Behandlung sowie Problembehebungen für die Serialisierung.
Das Paket wird unabhängig vom PowerShell-Worker versioniert. Auf diese Weise können Benutzer neue Features und Problembehebungen integrieren, sobald sie verfügbar sind, und gleichzeitig Breaking Changes durch automatische Upgrades vermeiden.
Die Wiedergabelogik ist schneller und zuverlässiger: Sie verwendet die gleiche Wiedergabe-Engine wie das isolierte DF SDK für C#.

Veralteter Plan für das integrierte DF PowerShell SDK

Das integrierte DF SDK im PowerShell-Worker bleibt für PowerShell 7.4, 7.2 und frühere Versionen verfügbar.

Wir haben vor, irgendwann eine neue Hauptversion des PowerShell-Workers ohne das integrierte SDK zu veröffentlichen. Benutzer müssen das SDK daher mithilfe dieses eigenständigen Pakets separat installieren. Die Installationsschritte werden unten beschrieben.

Installieren und Aktivieren des SDK

In diesem Abschnitt erfahren Sie, wie Sie ein neues eigenständiges SDK in Ihrer vorhandenen App installieren und aktivieren.

Voraussetzungen

Für das eigenständige PowerShell SDK sind die folgenden Mindestversionen erforderlich:

Azure Functions-Runtime v4.16 oder höher
Azure Functions Core Tools v4.0.5095 oder höher (bei lokaler Ausführung)
Azure Functions PowerShell-App für PowerShell 7.2 oder höher

Abonnieren des eigenständigen DF SDK

Die folgende Anwendungseinstellung ist erforderlich, um das eigenständige PowerShell SDK auszuführen:

Name: ExternalDurablePowerShellSDK
Wert: "true"

Mit dieser Anwendungseinstellung wird das integrierte Durable SDK für PowerShell-Versionen 7.2 und höher deaktiviert, sodass der Worker das externe SDK verwenden muss.

Wenn die Ausführung lokal mit Azure Functions Core Tools erfolgt, sollten Sie diese Einstellung Ihrer Datei local.settings.json hinzufügen. Wenn die Ausführung in Azure erfolgt, führen Sie die folgenden Schritte mit dem Tool Ihrer Wahl aus:

Ersetzen Sie <FUNCTION_APP_NAME> und <RESOURCE_GROUP_NAME> im vorherigen Beispiel durch den Namen Ihrer Funktions-App bzw. durch den Namen der Ressourcengruppe.

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

Ersetzen Sie <FUNCTION_APP_NAME> und <RESOURCE_GROUP_NAME> im vorherigen Beispiel durch den Namen Ihrer Funktions-App bzw. durch den Namen der Ressourcengruppe.

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

Stellen Sie sicher, dass die Azure Functions-Erweiterung für VS Code installiert ist.
Drücken Sie F1, um die Befehlspalette zu öffnen. Suchen Sie in der Befehlspalette den Befehl Azure Functions: Add New Setting..., und wählen Sie ihn aus.
Wählen Sie Ihr Abonnement und Ihre Funktions-App aus, wenn Sie dazu aufgefordert werden.
Geben Sie ExternalDurablePowerShellSDK als Namen ein, und drücken Sie dann die EINGABETASTE.
Geben Sie "true" als Wert ein, und drücken Sie dann die EINGABETASTE.

Installieren und Importieren des SDK

Sie haben zwei Möglichkeiten, um das SDK-Pakets zu installieren: als verwaltete Abhängigkeit oder als benutzerdefiniertes Modul. In diesem Abschnitt werden beide Optionen beschrieben, es ist aber lediglich eine erforderlich.

Installationsoption 1: Verwenden von verwalteten Abhängigkeiten

Um das SDK als verwaltete Abhängigkeit zu installieren, folgen Sie dem Leitfaden zu verwalteten Abhängigkeiten. Weitere Informationen finden Sie im Leitfaden. Zusammenfassend müssen Sie zunächst sicherstellen, dass ihr „host.json“ einen „managedDependency“-Abschnitt enthält, in dem eine „enabled“-Eigenschaft auf „true“ festgelegt ist. Unten finden Sie ein Beispiel „host.json“, das diese Anforderung erfüllt:

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

Danach müssen Sie einfach einen Eintrag für das DF SDK in Ihrer „requirements.psd1“-Datei angeben, wie im folgenden Beispiel gezeigt wird:

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

Installationsoption 2: Verwenden von benutzerdefinierten Modulen

Um das eigenständige DF SDK als benutzerdefiniertes Modul zu installieren, folgen Sie dem Leitfaden zum Erstellen eines Modulordners auf App-Ebene befolgen. Weitere Informationen finden Sie in den oben genannten Dokumentationen. Zusammenfassend müssen Sie das SDK-Paket in einem „".\Modules"“-Verzeichnis platzieren, das sich im Stammverzeichnis Ihrer App befindet.

Beispielsweise können Sie das eigenständige SDK aus dem Stammverzeichnis Ihrer Anwendung und nach dem Erstellen eines „".\Modules"“-Verzeichnisses folgendermaßen in das Modulverzeichnis herunterladen:

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

Importieren des SDK

Der letzte Schritt besteht im Importieren des SDK in Ihre Codesitzung. Importieren Sie hierzu das PowerShell SDK über „Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop“ in Ihre „profile.ps1“-Datei. Wenn Ihre App beispielsweise mithilfe von Vorlagen erstellt wurde, sieht Ihre „profile.ps1“-Datei möglicherweise so aus:

# 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

Dies sind alle erforderlichen Schritte, um das nächste PowerShell SDK zu verwenden. Führen Sie Ihre App wie gewohnt über „func host start“ in Ihrem Terminal aus, um mit der Verwendung des SDK zu beginnen.

Migrationsleitfaden

In diesem Abschnitt werden die Schnittstellen- und Verhaltensänderungen beschrieben, die Sie bei der Verwendung des neuen SDK erwarten können.

Neue Cmdlets

„Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input>“ ist ein neues CmdLet, mit dessen Hilfe Benutzer Suborchestratoren in ihren Workflows verwenden können.

Geänderte Cmdlets

Das CmdLet „Get-DurableTaskResult -Task <task>“ akzeptiert jetzt nur noch einen einzelnen Task als Argument und keine Liste mehr.

Verhaltensänderung

Ausnahmen, die von Aktivitäten ausgelöst werden, die mit „Wait-DurableTask“ geplant wurden (wie im Fan-Out/Fan-In-Muster), werden nicht mehr im Hintergrund ignoriert. Stattdessen gibt das CmdLet jetzt bei einer Ausnahme diese an den Orchestrator weiter, sodass sie vom Benutzercode verarbeitet werden kann.
NULL-Werte werden nicht mehr aus der Ergebnisliste eines „Wait-DurableTask“-Aufrufs (d. h. WhenAll) gelöscht. Dies bedeutet, dass ein erfolgreicher Aufruf von „Wait-DurableTask“ ohne das „-Any“-Flag ein Array der gleichen Größe wie die Anzahl der geplanten Aufgaben zurückgeben sollte.

Support erhalten, Feedback geben und Änderungen vorschlagen

Während der Vorschauphase dieses Release führt das eigenständige SDK möglicherweise noch einige weitere Änderungen ein. Diese Änderungen können von der Community beeinflusst werden. Feedback und Vorschläge können daher an das neue GitHub-Repository des SDK übermittelt werden.

Freigeben über