Le versioni di Durable Functions e la guida alla migrazione

Durable Functions è un'estensione di Funzioni di Azure e Azure Processi Web che consente di scrivere funzioni con stato in un ambiente serverless. L'estensione gestisce automaticamente lo stato, i checkpoint e i riavvii. Se non si ha già familiarità con Durable Functions, vedere la documentazione introduttiva.

Riepilogo della versione

Versione Status Modifiche chiave
v3.x Corrente (scelta consigliata) Aggiornamento Archiviazione di Azure SDK, miglioramento dell'efficienza dei costi, nessuna modifica del codice da aggiornare dalla versione 2.x
v2.x Gestito (solo correzioni di bug e sicurezza) Entità durevoli, DURABLE HTTP
v1.x Fine del supporto di settembre 2026 Legacy

Novità di v3.x

Il pacchetto Microsoft.Azure.WebJobs.Extensions.DurableTask v3 (definito WebJobs.Extensions.DurableTask nelle sezioni successive) è la versione consigliata corrente. L'aggiornamento dalla versione 2.x non richiede modifiche al codice . È sufficiente aggiornare le dipendenze del pacchetto. Questo aggiornamento viene considerato solo una modifica di rilievo per i clienti che eseguono app Durable C# che usano il modello in-process.

Annotazioni

Il pacchetto out-of-process Durable Functions .NET, Microsoft.Azure.Functions.Worker.Extensions.DurableTask, fa riferimento a Microsoft.Azure.WebJobs.Extensions.DurableTask come assembly sottostante. Pertanto, questo aggiornamento si applica anche a Microsoft. Azure. Functions.Worker.Extensions.DurableTask, a partire dalla versione 1.2.x.

Aggiornamento Archiviazione di Azure SDK

Per impostazione predefinita, Durable Functions usare Archiviazione di Azure come back-end di archiviazione per salvare in modo permanente lo stato dell'applicazione. In WebJobs.Extensions.DurableTask v3 il back-end Archiviazione di Azure è stato aggiornato per usare le versioni più recenti degli SDK di Archiviazione di Azure: Azure. Data.Tables, Azure. Storage.Blobs e Azure. Storage.Queues. Questi SDK offrono un supporto avanzato per l'identità gestita, prestazioni migliori, gestione dei dati più efficiente e maggiore sicurezza rispetto ai pacchetti legacy Microsoft.Azure.Storage.* usati in v2.x.

Miglioramento dell'efficienza dei costi (per il provider di Archiviazione di Azure)

Nel back-end di Archiviazione di Azure, il gestore della partizione è responsabile della distribuzione di partizioni/code di controllo tra i processi di lavoro. Il pacchetto WebJobs.Extensions.DurableTask v3 usa Gestione partizioni V3 per impostazione predefinita, che è una nuova progettazione che sfrutta le tabelle Azure per gestire le assegnazioni di partizione anziché Azure lease BLOB. Questa progettazione può ridurre significativamente i costi di archiviazione semplificando il debug. Quando si usa Partition Manager V3, viene creata una nuova tabella denominata Partitions, nell'account di archiviazione, consentendo di controllare facilmente le informazioni sulla partizione.

Rimozione del supporto per il runtime Funzioni di Azure v1

WebJobs.Extensions.DurableTask v3 non supporta più la versione 1.x del runtime di Funzioni di Azure, il supporto per il quale è pianificato per terminare September 2026. Se è necessario usare il runtime delle Funzioni v1, si prega di usare una versione dell'estensione Durable Functions inferiore a v2.11.0. Tenere presente che quando giunge il termine pianificato del supporto, Durable Functions perderà anche il supporto per il runtime v1.

Aggiornamento della destinazione del runtime .NET

WebJobs.Extensions.DurableTask v3 aggiorna il runtime di destinazione da .NET Core 3.1 a .NET 6, offrendo prestazioni migliorate e compatibilità migliorata con le funzionalità e le librerie di .NET moderne. Questo aggiornamento è allineato alle versioni future dei bundle di estensioni Funzioni di Azure.

Eseguire la migrazione da v2.x a v3.x

La migrazione dalla versione 2.x alla versione 3.x non richiede modifiche al codice. È sufficiente aggiornare le dipendenze per iniziare a usare le nuove funzionalità.

Eseguire l'aggiornamento alla versione 4.22.0 o successiva del bundle di estensione di Funzioni di Azure.

Compatibilità del downgrade (da v3.x a v2.x)

WebJobs.Extensions.DurableTask v3 usa una codifica di testo diversa per Archiviazione di Azure SDK (Base64) rispetto alla versione 2 (UTF-8). Se è necessario ripristinare da v3.x a v2.x, usare le versioni minime seguenti per garantire la compatibilità con le versioni precedenti:

  • modello In-process:v2.13.5 o versione più recente.
  • Modello di lavoro isolato:v1.1.5 o versione successiva (se si ripristina dalla versione 1.2.x o successiva).

Ripristinare una versione del bundle di estensione precedente alla 4.22.0.

Supporto e manutenzione di v2.x

WebJobs.Extensions.DurableTask v2.x continua a ricevere aggiornamenti della sicurezza e correzioni di bug, assicurandosi che le applicazioni esistenti rimangano sicure e stabili. Tuttavia, tutte le nuove funzionalità e i miglioramenti vengono aggiunti esclusivamente a v3.x. Per questo motivo, è consigliabile eseguire l'aggiornamento a WebJobs.Extensions.DurableTask v3 non appena è possibile sfruttare le funzionalità più recenti e i miglioramenti continui.

Funzionalità introdotte nella versione 2.x

Le funzionalità seguenti sono disponibili in Durable Functions 2.x e versioni successive in tutte le lingue supportate.

Annotazioni

I dettagli dell'API in-process .NET in questa sezione non si applicano al modello di lavoro isolato. Per linee guida sui lavoratori isolati, vedere la panoramica del processo isolato di Durable Functions.

Entità durevoli

Durable Functions supporta funzioni entity per la lettura e l'aggiornamento di piccole parti di stato, note come entità durable. Come le funzioni dell'agente di orchestrazione, le funzioni di entità sono funzioni con un tipo di trigger speciale, trigger di entità. A differenza delle funzioni dell'agente di orchestrazione, le funzioni di entità non hanno vincoli di codice specifici. Le funzioni di entità inoltre gestiscono lo stato in modo esplicito anziché rappresentarlo in modo implicito usando il flusso di controllo.

Per altre informazioni, vedere l'articolo sulle entità durevoli .

HTTP durevole

Durable Functions include una funzionalità HTTP durevole che consente di:

  • Chiamare le API HTTP direttamente dalle funzioni di orchestrazione (con alcune limitazioni documentate).
  • Implementare il polling automatico dello stato HTTP 202 sul lato client.
  • Usa il supporto integrato per identità gestite di Azure.

Per altre informazioni, vedere l'articolo sulle funzionalità HTTP .

Eseguire la migrazione da 1.x a 2.x

Importante

La versione 1.x del runtime di Funzioni di Azure raggiunge la fine del supporto in September 2026. Se si è ancora in versione 1.x, pianificare la migrazione a breve.

Questa sezione descrive come eseguire la migrazione della versione 1.x esistente Durable Functions alla versione 2.x per sfruttare le nuove funzionalità.

Aggiornare l'estensione Durable Functions

Installare la versione 2.x più recente dell'estensione delle associazioni Durable Functions nel progetto.

Durable Functions 2.x è disponibile a partire dalla versione 2.x del bundle di estensione Funzioni di Azure.

Il supporto per Python in Durable Functions richiede Durable Functions 2.x o versioni successive.

Per aggiornare la versione del bundle di estensione nel progetto, aprire host.json e aggiornare la sezione per usare la extensionBundle versione 4.x ([4.*, 5.0.0)).

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.*, 5.0.0)"
    }
}

Durable Functions 2.x è disponibile a partire dalla versione 2.x del bundle di estensione Funzioni di Azure.

Per aggiornare la versione del bundle di estensione nel progetto, aprire host.json e aggiornare la sezione per usare la extensionBundle versione 4.x ([4.*, 5.0.0)).

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.*, 5.0.0)"
    }
}

Annotazioni

Se Visual Studio Code non visualizza i modelli corretti dopo aver modificato la versione del bundle di estensione, ricaricare la finestra eseguendo il comando Developer: Ricarica finestra (Ctrl+R in Windows e Linux, Command+R in macOS).

Durable Functions 2.x è disponibile a partire dalla versione 2.x del bundle di estensione Funzioni di Azure.

Per aggiornare la versione del bundle di estensione nel progetto, aprire host.json e aggiornare la sezione per usare la extensionBundle versione 4.x ([4.*, 5.0.0)).

{
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[4.*, 5.0.0)"
    }
}

Aggiornare il progetto di .NET per usare la versione più recente dell'estensione Durable Functions binding.

Per altre informazioni, vedere Register Funzioni di Azure binding extensions.

Aggiornare il codice Durable Functions

Durable Functions 2.x introduce diverse modifiche significative. Le applicazioni di Durable Functions 1.x non sono compatibili con Durable Functions 2.x senza apportare modifiche al codice. Questa sezione elenca alcune delle modifiche da apportare durante l'aggiornamento delle funzioni 1.x alla versione 2.x.

Schema Host.json

Durable Functions 2.x usa un nuovo schema host.json. Le principali modifiche apportate dalla versione 1.x includono:

  • "storageProvider" (e la sottosezione "azureStorage") per la configurazione specifica dell'archiviazione.
  • "tracing" per la configurazione di tracciamento e registrazione.
  • "notifications" (e la "eventGrid" sottosezione) per la configurazione delle notifiche di Event Grid.

Per informazioni dettagliate, vedere la documentazione di riferimento Durable Functions host.json.

Modifiche al nome predefinito dell'hub di attività

Nella versione 1.x, se un nome dell'hub attività non è stato specificato in host.json, per impostazione predefinita è "DurableFunctionsHub". Nella versione 2.x, il nome predefinito dell'hub attività è ora derivato dal nome dell'app per le funzioni. Per questo motivo, se non è stato specificato un nome dell'hub attività durante l'aggiornamento alla versione 2.x, il codice funziona con un nuovo hub attività e tutte le orchestrazioni in corso non hanno più un'applicazione che le elabora. Per risolvere questo problema, è possibile impostare esplicitamente il nome dell'hub attività sul valore predefinito v1.x di "DurableFunctionsHub" oppure seguire le indicazioni sulla distribuzione senza tempi di inattività per informazioni dettagliate su come gestire le modifiche di rilievo per le orchestrazioni in corso.

Modifiche all'interfaccia pubblica nelle Durable Functions

Nella versione 1.x i vari oggetti context supportati da Durable Functions hanno classi di base astratte destinate all'uso negli unit test. Nell'ambito di Durable Functions 2.x, queste classi base astratte vengono sostituite con le interfacce.

La tabella seguente rappresenta le modifiche principali:

1.x 2.x
DurableOrchestrationClientBase IDurableOrchestrationClient oppure IDurableClient
DurableOrchestrationContext oppure DurableOrchestrationContextBase IDurableOrchestrationContext
DurableActivityContext oppure DurableActivityContextBase IDurableActivityContext
OrchestrationClientAttribute DurableClientAttribute

Nel caso in cui una classe base astratta conteneva metodi virtuali, questi metodi virtuali sono stati sostituiti da metodi di estensione definiti in DurableContextExtensions.

modifiche di function.json

In Durable Functions 1.x, l'associazione client di orchestrazione usa un type di orchestrationClient. La versione 2.x usa durableClient invece.

Generare le modifiche agli eventi

In Durable Functions 1.x, chiamare l'API raise event e specificare un'istanza inesistente portava a un fallimento silenzioso. A partire dalla versione 2.x, la generazione di un evento per un'orchestrazione inesistente comporta un'eccezione.

Contenuti correlati

  • Last updated on