Condividi tramite

Guida all'SDK di PowerShell per Durable Functions autonomo

  • Articolo

PowerShell SDK di Durable Functions (DF) è ora disponibile, in anteprima, come pacchetto autonomo in PowerShell Gallery: AzureFunctions.PowerShell.Durable.SDK. Quando questo pacchetto SDK è disponibile a livello generale, sarà il mezzo consigliato per la creazione di app Durable Functions con PowerShell. In questo articolo vengono illustrati i vantaggi di questa modifica e le modifiche che è possibile prevedere quando si adotta questo nuovo pacchetto.

Nota

Questo pacchetto è attualmente in anteprima.

Motivazione alla base dell'SDK autonomo

L'SDK DF precedente è stato integrato nel ruolo di lavoro del linguaggio di PowerShell. Questo approccio è stato fornito con il vantaggio che le app durable Functions possono essere create per impostazione predefinita per Funzioni di Azure utenti di PowerShell. Tuttavia, è venuto anche con varie carenze:

  • Nuove funzionalità, correzioni di bug e altre modifiche dipendono dalla frequenza di rilascio del ruolo di lavoro di PowerShell.
  • A causa della natura dell'aggiornamento automatico del ruolo di lavoro di PowerShell, DF SDK doveva essere conservativo per la correzione dei bug, in quanto qualsiasi modifica del comportamento potrebbe costituire una modifica che causa un'interruzione.
  • L'algoritmo di riproduzione usato dall'SDK predefinito di DF era obsoleto: altri SDK DF hanno già usato un'implementazione più veloce e affidabile.

Creando un pacchetto DF PowerShell SDK autonomo, è possibile superare queste carenze. Questi sono i vantaggi dell'uso di questo nuovo pacchetto SDK autonomo:

  • Questo SDK include molti miglioramenti altamente richiesti, ad esempio una migliore gestione di eccezioni e valori Null e correzioni di serializzazione.
  • Il pacchetto viene eseguito in modo indipendente dal ruolo di lavoro di PowerShell. Ciò consente agli utenti di incorporare nuove funzionalità e correzioni non appena sono disponibili, evitando al contempo modifiche di rilievo dagli aggiornamenti automatici.
  • La logica di riproduzione è più veloce e più affidabile: usa lo stesso motore di riproduzione dell'SDK isolato di DF per C#.

Piano di deprecazione per DF PowerShell SDK predefinito

L'SDK predefinito DF nel ruolo di lavoro di PowerShell rimarrà disponibile per PowerShell 7.4, 7.2 e versioni precedenti.

Alla fine si prevede di rilasciare una nuova versione principale del ruolo di lavoro di PowerShell senza l'SDK predefinito. A questo punto, gli utenti dovranno installare l'SDK separatamente usando questo pacchetto autonomo; I passaggi di installazione sono descritti di seguito.

Installare e abilitare l'SDK

Vedere questa sezione per informazioni su come installare e abilitare un nuovo SDK autonomo nell'app esistente.

Prerequisiti

PowerShell SDK autonomo richiede le versioni minime seguenti:

Acconsentire esplicitamente all'SDK DF autonomo

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

  • Nome: ExternalDurablePowerShellSDK
  • Valore: "true"

Questa impostazione dell'applicazione disabiliterà durable SDK predefinito per PowerShell versione 7.2 e successive, forzando il ruolo di lavoro 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:

Sostituire <FUNCTION_APP_NAME> e <RESOURCE_GROUP_NAME> rispettivamente con il nome dell'app per le funzioni e del gruppo di risorse.

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

Installare e importare l'SDK

Sono disponibili due opzioni per installare il pacchetto SDK: può essere installato usando dipendenze gestite o incluso nel contenuto dell'app. In questa sezione vengono descritte entrambe le opzioni, ma solo una di esse è necessaria.

Opzione di installazione 1: Usare le dipendenze gestite

Per installare l'SDK come dipendenza gestita, è necessario seguire le indicazioni sulle dipendenze gestite. Per informazioni dettagliate, vedere le linee guida. In breve, è prima necessario assicurarsi che host.json contenga una managedDependency sezione con una enabled proprietà impostata su true. Di seguito è riportato un esempio host.json che soddisfa questo requisito:

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

Quindi è sufficiente specificare una voce per DF SDK nel requirements.psd1 file, come nell'esempio seguente:

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

Opzione di installazione 2: Usare moduli personalizzati

Per installare DF SDK autonomo come modulo personalizzato, è necessario seguire le indicazioni relative all'inclusione di moduli nel contenuto dell'app. Assicurarsi di esaminare la documentazione indicata in precedenza per informazioni dettagliate. In sintesi, dovrai inserire il pacchetto SDK all'interno di una ".\Modules" directory che si trova nella radice dell'app.

Ad esempio, dall'interno della radice dell'applicazione e dopo aver creato una ".\Modules" directory, è possibile scaricare l'SDK autonomo nella directory dei moduli, ad esempio:

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

Importazione dell'SDK

Il passaggio finale consiste nell'importare l'SDK nella sessione del codice. A tale scopo, importare PowerShell SDK tramite Import-Module AzureFunctions.PowerShell.Durable.SDK -ErrorAction Stop nel profile.ps1 file. Ad esempio, se l'app è stata sottoposta a scaffolding tramite modelli, il profile.ps1 file potrebbe terminare alla ricerca di questo tipo:

# 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

Questi sono tutti i passaggi necessari per usare l'SDK di PowerShell successivo. Eseguire l'app come di consueto, tramite func host start il terminale per iniziare a usare l'SDK.

Guida alla migrazione

In questa sezione vengono descritte le modifiche dell'interfaccia e del comportamento che è possibile prevedere quando si usa il nuovo SDK.

Nuovi cmdLet

  • Invoke-DurableSubOrchestrator -FunctionName <Name> -Input <Input> è un nuovo CmdLet che consente agli utenti di utilizzare i suborchestrator nei flussi di lavoro.

CmdLet modificati

  • CmdLet Get-DurableTaskResult -Task <task> accetta ora solo un'unica attività come argomento, anziché accettare un elenco di attività.

Modifiche comportamentali

  • Le eccezioni generate dalle attività pianificate con Wait-DurableTask (come nel modello Fan-Out/Fan-In) non vengono più ignorate automaticamente. Invece, in un'eccezione, CmdLet propaga tale eccezione all'agente di orchestrazione in modo che possa essere gestita dal codice utente.
  • I valori Null non vengono più eliminati dall'elenco dei risultati di una Wait-DurableTask chiamata (ad esempio WhenAll). Ciò significa che una chiamata corretta di Wait-DurableTask senza il -Any flag deve restituire una matrice con le stesse dimensioni del numero di attività pianificate.

Dove ottenere supporto, fornire commenti e suggerimenti e suggerire modifiche

Durante la fase di anteprima di questa versione, l'SDK autonomo può introdurre altre modifiche. Queste modifiche possono essere influenzate dalla community in modo da segnalare eventuali commenti e suggerimenti al nuovo repository GitHub dell'SDK.