Condividi tramite

Guida all'SDK di PowerShell autonomo Durable Functions

  • Articolo

PowerShell SDK Durable Functions (DF) è ora disponibile, in anteprima, come pacchetto autonomo nel PowerShell Gallery: AzureFunctions.PowerShell.Durable.SDK. Una volta che 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 Durable Functions le app 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 di aggiornamento automatico del ruolo di lavoro di PowerShell, DF SDK doveva essere conservativo per correggere i bug perché qualsiasi modifica del comportamento potrebbe costituire una modifica di rilievo.
  • L'algoritmo di riproduzione usato dall'SDK predefinito di DF è obsoleto: altri SDK di DF hanno già usato un'implementazione più veloce e affidabile.

Creando un pacchetto DF PowerShell SDK autonomo, siamo in grado di 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 sottoposto a controllo delle versioni indipendentemente dal ruolo di lavoro di PowerShell. Ciò consente agli utenti di incorporare nuove funzionalità e correzioni non appena sono disponibili, evitando anche 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 di DF nel ruolo di lavoro di PowerShell rimarrà disponibile per PowerShell 7.4, 7.2 e versioni precedenti.

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 in locale usando Funzioni di Azure Core Tools, è necessario 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> con il nome rispettivamente 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 l'installazione del pacchetto SDK: può essere installata come dipendenza gestita o come modulo personalizzato. 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 sintesi, è prima di tutto necessario assicurarsi che host.json contenga una sezione con una enabledmanagedDependency 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 per la creazione di una cartella di moduli a livello di app. Assicurarsi di esaminare la documentazione menzionata 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 modules, 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 finire per cercare di conseguenza:

# 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 nel 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 CmdLets

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

CmdLets modificati

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

Modifiche funzionali

  • 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, inviare commenti e suggerimenti e suggerire modifiche

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