Leitfaden zum eigenständigen Durable Functions PowerShell SDK

Das eigenständige Durable Functions PowerShell SDK (AzureFunctions.PowerShell.Durable.SDK) ist der empfohlene Ansatz zum Erstellen Durable Functions Apps mit PowerShell. Es ersetzt das integrierte SDK durch eine schnellere Wiedergabelogik (dasselbe Modul wie das isolierte C#-SDK), unabhängige Versionsverwaltung und verbesserte Ausnahmebehandlung, Nullwertbehandlung und Serialisierung. Das integrierte SDK bleibt für PowerShell 7.4 und früher verfügbar, wird aber in einer zukünftigen Hauptversion des PowerShell-Workers entfernt.

Migrationscheckliste

Verwenden Sie die folgende Checkliste, um den Fortschritt in jedem Migrationsschritt nachzuverfolgen:

Installieren des eigenständigen SDK

Führen Sie die folgenden Schritte aus, um das eigenständige SDK in Ihrer vorhandenen App zu installieren und zu aktivieren.

Überprüfen der 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.4 oder höher

Aktivieren des eigenständigen 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:

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

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

Installieren des SDK-Pakets

Sie haben zwei Optionen zum Installieren des SDK-Pakets. Verwenden Sie verwaltete Abhängigkeiten (empfohlen für die meisten Apps) oder bündeln Sie das Modul mit Ihren App-Inhalten, wenn Sie eine bestimmte Version festlegen müssen oder Ihre Bereitstellung verwaltete Abhängigkeiten nicht unterstützt. Es ist nur eine Option erforderlich.

Option 1: Verwenden von verwalteten Abhängigkeiten (empfohlen)

Um das SDK als verwaltete Abhängigkeit zu installieren, befolgen Sie die Richtlinien für verwaltete Abhängigkeiten. Stellen Sie zunächst sicher, dass Ihr host.json einen managedDependency Abschnitt enthält, der enabled auf true festgelegt ist:

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

Geben Sie dann einen Eintrag für das SDK in Ihrer requirements.psd1 Datei an:

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

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

Um das SDK mit Ihrer App zu bündeln, platzieren Sie das SDK-Paket in einem ".\Modules" Verzeichnis im Stammverzeichnis Ihrer App. Weitere Informationen finden Sie unter Einschließen von Modulen in App-Inhalten.

Erstellen Sie aus Ihrem Anwendungsstamm das Verzeichnis, und laden Sie das SDK herunter:

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

Importieren des SDK

Fügen Sie die folgende Zeile zu Ihrer profile.ps1 Datei hinzu, um das SDK bei jedem Kaltstart zu importieren:

Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop

Starten Sie Ihre App

Starten Sie Ihre App mit func host start. Das eigenständige SDK ist jetzt aktiv.

Migrieren aus dem integrierten SDK

Wenn Sie eine vorhandene App aus dem integrierten SDK migrieren, lesen Sie die folgenden Schnittstellen- und Verhaltensänderungen.

Neue Cmdlets

Geänderte Cmdlets

Änderungen des Verhaltens

Ausnahmebehandlung in Wait-DurableTask

Ausnahmen, die von Aktivitäten ausgelöst werden, die mit Wait-DurableTask (Fan-out/Fan-In-Schema) geplant sind, werden nicht mehr ohne Beachtung ignoriert. Das Cmdlet gibt nun die Ausnahme an den Orchestrator weiter, damit Sie sie im Code behandeln können.

Integriertes SDK — Ausnahmen wurden stillschweigend ignoriert.

# Exceptions from failed activities were lost
$tasks = @()
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
$tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
$results = Wait-DurableTask -Task $tasks
# No error even if an activity failed

Eigenständiges SDK – Ausnahmen werden an den Orchestrator weitergegeben:

try {
    $tasks = @()
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item1" -NoWait
    $tasks += Invoke-DurableActivity -FunctionName "RiskyActivity" -Input "item2" -NoWait
    $results = Wait-DurableTask -Task $tasks
} catch {
    # Handle the activity failure
    Write-Host "An activity failed: $_"
}

Nullwerte, die in Wait-DurableTask Ergebnissen erhalten bleiben

Nullwerte werden nicht mehr aus der Ergebnisliste eines Wait-DurableTask (WhenAll)-Aufrufs gelöscht. Ein erfolgreicher Aufruf ohne das -Any Flag gibt jetzt ein Array derselben Größe wie die Anzahl der geplanten Vorgänge zurück, einschließlich $null Einträge für Aktivitäten, die NULL zurückgegeben haben.

Integriertes SDK – NULL-Ergebnisse wurden gelöscht:

# 3 tasks scheduled, but if one returned $null, results had only 2 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Could be 2 instead of 3

Eigenständiges SDK – NULL-Ergebnisse bleiben erhalten:

# 3 tasks scheduled, results always has 3 items
$results = Wait-DurableTask -Task $tasks
$results.Count  # Always 3, with $null for activities that returned null

SDK-Referenz

Die vollständige Cmdlet-Referenz finden Sie unter AzureFunctions.PowerShell.Durable.SDK Module. Nach dem Importieren des Moduls können Sie auch ausführen Get-Help *-Durable* , um alle verfügbaren Cmdlets aufzulisten oder Get-Help <cmdlet-name> -Full um eine detaillierte Verwendung zu ermöglichen.

Unterstützung erhalten

Melden Sie Fehler und Featureanforderungen im GitHub-Repository des SDK.

Nächste Schritte

• Erstellen Sie eine Durable Functions-App mit PowerShell
• Muster und Konzepte für dauerhafte Funktionen
• PowerShell-Entwicklerreferenz für Azure Functions