Guida all'SDK di PowerShell per Durable Functions indipendente

L'Durable Functions PowerShell SDK autonomo (AzureFunctions.PowerShell.Durable.SDK) è l'approccio consigliato per la creazione di app Durable Functions con PowerShell. Sostituisce l'SDK predefinito con logica di riproduzione più veloce (lo stesso motore dell'SDK isolato C#), il controllo delle versioni indipendenti e la gestione delle eccezioni migliorata, la gestione dei valori Null e la serializzazione. L'SDK predefinito rimane disponibile per PowerShell 7.4 e versioni precedenti, ma verrà rimosso in una versione principale futura del ruolo di lavoro di PowerShell.

Elenco di controllo per la migrazione

Usare l'elenco di controllo seguente per tenere traccia dello stato di avanzamento in ogni passaggio della migrazione:

Installare l'SDK autonomo

Seguire questa procedura per installare e abilitare l'SDK autonomo nell'app esistente.

Verificare i prerequisiti

PowerShell SDK autonomo richiede le versioni minime seguenti:

• Runtime di Funzioni di Azure v4.16+
• Funzioni di Azure Core Tools v4.0.5095+ (se in esecuzione in locale)
• App PowerShell per Funzioni di Azure per PowerShell 7.4 o versione successiva

Abilitare l'SDK autonomo

Per eseguire PowerShell SDK autonomo, è necessaria l'impostazione dell'applicazione seguente:

• Nome: ExternalDurablePowerShellSDK
• Valore: "true"

Questa impostazione dell'applicazione disabilita l'SDK Durable integrato per PowerShell versioni 7.4 e successive, forzando il worker a usare l'SDK esterno.

Se si esegue localmente usando Funzioni di Azure Core Tools, è consigliabile aggiungere questa impostazione al local.settings.json file. Se si esegue in Azure, seguire questa procedura con lo strumento preferito:

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

Installare il pacchetto SDK

Sono disponibili due opzioni per l'installazione del pacchetto SDK. Usare le dipendenze gestite (consigliate per la maggior parte delle app) o aggregare il modulo con il contenuto dell'app se è necessario aggiungere una versione specifica o la distribuzione non supporta le dipendenze gestite. È necessaria una sola opzione.

Opzione 1: Usare le dipendenze gestite (scelta consigliata)

Per installare l'SDK come dipendenza gestita, seguire le indicazioni sulle dipendenze gestite. Verificare prima di tutto che host.json contenga una managedDependency sezione con enabled impostato su true:

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

Specificare quindi una voce per l'SDK nel requirements.psd1 file:

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

Opzione 2: Includere il modulo SDK nel contenuto dell'app

Per aggregare l'SDK con l'app, inserire il pacchetto SDK all'interno di una ".\Modules" directory nella radice dell'app. Per altre informazioni, vedere Inclusione di moduli nel contenuto dell'app.

Dalla radice dell'applicazione: creare una nuova directory e scaricare l'SDK.

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

Importare l'SDK

Aggiungere la riga seguente al file profile.ps1 per importare l'SDK in ogni avvio a freddo.

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

Avvia la tua app

Avviare l'app con func host start. L'SDK autonomo è ora attivo.

Eseguire la migrazione dall'SDK predefinito

Se si esegue la migrazione di un'app esistente dall'SDK predefinito, esaminare l'interfaccia e le modifiche comportamentali seguenti.

I nuovi cmdlet

Cmdlet modificati

Modifiche comportamentali

Gestione delle eccezioni in Wait-DurableTask

Le eccezioni generate dalle attività pianificate con Wait-DurableTask (come nel modello Fan-Out/Fan-In) non vengono più ignorate automaticamente. Il cmdlet ora propaga l'eccezione all'agente di orchestrazione in modo da poterla gestire nel codice.

SDK predefinito : le eccezioni sono state ingoiate in modo invisibile all'utente:

# 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

SDK autonomo : le eccezioni vengono propagate all'agente di orchestrazione:

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: $_"
}

I valori null vengono mantenuti nei Wait-DurableTask risultati

I valori Null non vengono più eliminati dall'elenco dei risultati di una Wait-DurableTask chiamata (WhenAll). Una chiamata con esito positivo senza il flag -Any restituisce ora una matrice con le stesse dimensioni del numero di attività pianificate, incluse le voci $null per le attività che hanno restituito null.

SDK integrato — i risultati nulli sono stati eliminati:

# 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

SDK autonomo: i risultati Null vengono mantenuti.

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

Informazioni di riferimento su SDK

Per informazioni di riferimento complete sui cmdlet, vedere AzureFunctions.PowerShell.Durable.SDK Module. Dopo aver importato il modulo, è anche possibile eseguire Get-Help *-Durable* per elencare tutti i cmdlet disponibili o Get-Help <cmdlet-name> -Full per un utilizzo dettagliato.

Ottenere supporto

Segnalare bug e richieste di funzionalità nel repository GitHub dell'SDK.

Passaggi successivi

• Creare un'app Durable Functions con PowerShell
• Modelli e concetti di Durable Functions
• Informazioni di riferimento per gli sviluppatori di PowerShell per Funzioni di Azure