Teilen über

Leitfaden zum eigenständigen Durable Functions PowerShell SDK

Das PowerShell-SDK für dauerhafte Funktionen (DF) ist jetzt als eigenständiges Modul im PowerShell-Katalog verfügbar: AzureFunctions.PowerShell.Durable.SDK. Dieses SDK ist jetzt allgemein verfügbar (GA) und ist der empfohlene Ansatz zum Erstellen dauerhafter Funktionen-Apps mit PowerShell. In diesem Artikel erläutern wir die Vorteile dieser Änderung sowie welche Änderungen Sie durch die Einführung dieses neuen Pakets erwarten können.

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 und frühere Versionen verfügbar.

Wir planen, in Zukunft eine neue Hauptversion des PowerShell-Workers ohne das integrierte SDK zu veröffentlichen. Zu diesem Zeitpunkt müssten Benutzer das SDK separat mit diesem eigenständigen Paket 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:

Abonnieren des eigenständigen DF SDK

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

  • Name: ExternalDurablePowerShellSDK
  • Wert: "true"

Diese Anwendungseinstellung deaktiviert das integrierte durable SDK für PowerShell-Versionen 7.4 und höher, wodurch der Worker gezwungen wird, das externe SDK zu verwenden.

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

Installieren und Importieren des SDK

Sie haben zwei Optionen zum Installieren des SDK-Pakets: Es kann mit verwalteten Abhängigkeiten oder gebündelt mit Dem App-Inhalt installiert werden. 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' = '2.*'
}

Installationsoption 2: Einschließen des SDK-Moduls in Den App-Inhalt

Um das eigenständige DF SDK in Ihre App-Inhalte einzuschließen, müssen Sie die Anleitungen zum Einschließen von Modulen in App-Inhalten 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.

SDK-Referenz

Die vollständige Referenz zu den SDK-Cmdlets und deren Parametern finden Sie im AzureFunctions.PowerShell.Durable.SDK-Modul .

Sie können das Get-Help Cmdlet auch verwenden, um detaillierte Beschreibungen der SDK-Cmdlets abzurufen. Um dies zu tun, müssen Sie das Modul zuerst importieren, wie im vorherigen Abschnitt gezeigt. Danach können Sie den folgenden Befehl ausführen, um die gesamte Liste der Cmdlets abzurufen:

Get-Help *-Durable*

Um detaillierte Hilfe zu einem bestimmten Cmdlet zu erhalten, einschließlich Verwendungsbeispielen, führen Sie Folgendes aus:

Get-Help Invoke-DurableOrchestration -Full

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 ist ein neues Cmdlet, mit dem Benutzer Suborchestratoren in ihren Workflows nutzen können.
  • Suspend-DurableOrchestration und Resume-DurableOrchestration sind neue Cmdlets, mit denen Benutzer Orchestrierungen anhalten bzw. fortsetzen können.

Geänderte Cmdlets

  • Das Get-DurableTaskResult Cmdlet akzeptiert nun nur einen einzelnen Vorgang als Argument, anstatt eine Liste von Aufgaben zu akzeptieren.
  • Das New-DurableRetryOptions Cmdlet wird umbenannt New-DurableRetryPolicy in (ein Alias für den alten Namen wird aus Gründen der Abwärtskompatibilität bereitgestellt).

Verhaltensänderungen

  • 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 verteilt das Cmdlet bei einer Ausnahme diese Ausnahme an den Orchestrator, sodass sie von 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.

Unterstützung erhalten und Feedback bereitstellen

Melden Sie feedback und Vorschläge an das GitHub-Repository des SDK.

  • Last updated on