Eseguire la migrazione da In-Process al modello di lavoro isolato

Questa guida illustra come eseguire la migrazione dell'applicazione Durable Functions dal modello in-process al modello di lavoro isolato.

Perché eseguire la migrazione?

Fine del supporto per il modello in-process

Microsoft ha annunciato che il modello in-process per .NET Azure Functions raggiunge la fine del supporto il 10 novembre 2026. Dopo questa data:

• Non vengono forniti aggiornamenti della sicurezza
• Non vengono rilasciate correzioni di bug
• Le nuove funzionalità sono disponibili solo nel modello di lavoro isolato

Vantaggi del modello di lavoro isolato

La migrazione al modello di lavoro isolato offre i vantaggi seguenti:

Prerequisiti

Prima di avviare la migrazione, assicurarsi di disporre dei prerequisiti seguenti:

• Azure Functions Core Tools v4.x o versione successiva
• .NET 8.0 SDK (o versione di .NET di destinazione)
• Visual Studio 2022 o VS Code with Azure Functions extension
• Familiarità con i concetti di Durable Functions

Panoramica della migrazione

Il processo di migrazione prevede questi passaggi principali:

1. Identificare le app di cui eseguire la migrazione
2. Aggiornare il file di progetto
3. Aggiungere Program.cs
4. Aggiornare i riferimenti ai pacchetti
5. Aggiornare il codice della funzione
6. Aggiornare local.settings.json
7. Testare localmente
8. Deploy in Azure

Identificare le app di cui eseguire la migrazione

Usare questo script di Azure PowerShell per trovare le app di funzione della tua sottoscrizione che usano il modello in-process.

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.Runtime -eq 'dotnet')
     {
          $AppInfo.Add($App.Name, $App.Runtime)
     }
}

$AppInfo

Le app che mostrano dotnet come runtime usano il modello in-process. Le app che utilizzano dotnet-isolated già usano il modello di lavoro isolato.

Aggiornare il file di progetto

Prima (in-process)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.1.1" />
    <PackageReference Include="Microsoft.Azure.WebJobs.Extensions.DurableTask" Version="2.13.0" />
  </ItemGroup>
</Project>

Dopo (processo di lavoro isolato)

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.17.2" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore" Version="1.2.1" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.DurableTask" Version="1.14.1" />
    <PackageReference Include="Microsoft.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

Modifiche chiave

• Aggiungere <OutputType>Exe</OutputType> - Il processo di lavoro isolato è un programma eseguibile
• Aggiungere <FrameworkReference Include="Microsoft.AspNetCore.App" /> - Per l'integrazione di ASP.NET Core
• Sostituire Microsoft.NET.Sdk.Functions con pacchetti Microsoft.Azure.Functions.Worker.*
• Sostituire Microsoft.Azure.WebJobs.Extensions.DurableTask con Microsoft.Azure.Functions.Worker.Extensions.DurableTask

Aggiungere Program.cs

Creare un nuovo Program.cs file nella radice del progetto:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
    })
    .Build();

host.Run();

Con i servizi personalizzati

Se si dispone di una FunctionsStartup classe, spostare la configurazione in Program.cs:

using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        // Application Insights
        services.AddApplicationInsightsTelemetryWorkerService();
        services.ConfigureFunctionsApplicationInsights();
        
        // Your custom services (previously in FunctionsStartup)
        services.AddSingleton<IMyService, MyService>();
        services.AddHttpClient<IApiClient, ApiClient>();
    })
    .Build();

host.Run();

Eliminare FunctionsStartup

Se disponi di Startup.cs con [assembly: FunctionsStartup(...)], eliminalo dopo aver trasferito la configurazione in Program.cs.

Aggiornare i riferimenti ai pacchetti

modifiche al pacchetto Durable Functions

Modifiche comuni ai pacchetti di estensione

Aggiornare il codice della funzione

Modifiche dello spazio dei nomi

// Before (In-Process)
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.DurableTask;
using Microsoft.Azure.WebJobs.Extensions.Http;

// After (Isolated Worker)
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.DurableTask;
using Microsoft.DurableTask.Client;
using Microsoft.DurableTask.Entities;

Modifiche dell'attributo della funzione

// Before (In-Process)
[FunctionName("MyOrchestrator")]

// After (Isolated Worker)
[Function(nameof(MyOrchestrator))]

Modifiche delle funzioni dell'agente di orchestrazione

Prima (in-process):

[FunctionName("OrderOrchestrator")]
public static async Task<OrderResult> RunOrchestrator(
    [OrchestrationTrigger] IDurableOrchestrationContext context,
    ILogger log)
{
    var order = context.GetInput<Order>();
    
    await context.CallActivityAsync("ValidateOrder", order);
    await context.CallActivityAsync("ProcessPayment", order.Payment);
    await context.CallActivityAsync("ShipOrder", order);
    
    return new OrderResult { Success = true };
}

Dopo (Lavoratore isolato):

[Function(nameof(OrderOrchestrator))]
public static async Task<OrderResult> OrderOrchestrator(
    [OrchestrationTrigger] TaskOrchestrationContext context)
{
    ILogger logger = context.CreateReplaySafeLogger(nameof(OrderOrchestrator));
    var order = context.GetInput<Order>();
    
    await context.CallActivityAsync("ValidateOrder", order);
    await context.CallActivityAsync("ProcessPayment", order.Payment);
    await context.CallActivityAsync("ShipOrder", order);
    
    return new OrderResult { Success = true };
}

Differenze principali

Modifiche delle funzioni di attività

Prima di (In corso):

[FunctionName("ValidateOrder")]
public static bool ValidateOrder(
    [ActivityTrigger] Order order,
    ILogger log)
{
    log.LogInformation("Validating order {OrderId}", order.Id);
    return order.Items.Any() && order.TotalAmount > 0;
}

Dopo (processo di lavoro isolato)

[Function(nameof(ValidateOrder))]
public static bool ValidateOrder(
    [ActivityTrigger] Order order,
    FunctionContext executionContext)
{
    ILogger logger = executionContext.GetLogger(nameof(ValidateOrder));
    logger.LogInformation("Validating order {OrderId}", order.Id);
    return order.Items.Any() && order.TotalAmount > 0;
}

Modifiche della funzione client

Prima (in-process):

[FunctionName("StartOrder")]
public static async Task<IActionResult> StartOrder(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequest req,
    [DurableClient] IDurableOrchestrationClient client,
    ILogger log)
{
    var order = await req.ReadFromJsonAsync<Order>();
    string instanceId = await client.StartNewAsync("OrderOrchestrator", order);
    
    return client.CreateCheckStatusResponse(req, instanceId);
}

Dopo (processo di lavoro isolato)

[Function("StartOrder")]
public static async Task<HttpResponseData> StartOrder(
    [HttpTrigger(AuthorizationLevel.Function, "post")] HttpRequestData req,
    [DurableClient] DurableTaskClient client,
    FunctionContext executionContext)
{
    ILogger logger = executionContext.GetLogger("StartOrder");
    var order = await req.ReadFromJsonAsync<Order>();
    string instanceId = await client.ScheduleNewOrchestrationInstanceAsync(
        nameof(OrderOrchestrator), 
        order
    );
    
    return await client.CreateCheckStatusResponseAsync(req, instanceId);
}

Modifiche al tipo di client

Modifiche ai criteri di ripetizione dei tentativi

In-process usa RetryOptions con CallActivityWithRetryAsync. Il lavoratore isolato usa TaskOptions con lo standard CallActivityAsync.

Prima (in-process):

var retryOptions = new RetryOptions(
    firstRetryInterval: TimeSpan.FromSeconds(5),
    maxNumberOfAttempts: 3);

string result = await context.CallActivityWithRetryAsync<string>(
    "MyActivity", retryOptions, input);

Dopo (processo di lavoro isolato)

var retryOptions = new TaskOptions(
    new TaskRetryOptions(new RetryPolicy(
        maxNumberOfAttempts: 3,
        firstRetryInterval: TimeSpan.FromSeconds(5))));

string result = await context.CallActivityAsync<string>(
    "MyActivity", input, retryOptions);

Modifiche alle funzioni di entità

Prima (in-process):

[FunctionName(nameof(Counter))]
public static void Counter([EntityTrigger] IDurableEntityContext ctx)
{
    switch (ctx.OperationName.ToLowerInvariant())
    {
        case "add":
            ctx.SetState(ctx.GetState<int>() + ctx.GetInput<int>());
            break;
        case "get":
            ctx.Return(ctx.GetState<int>());
            break;
    }
}

Dopo (processo di lavoro isolato)

[Function(nameof(Counter))]
public static Task Counter([EntityTrigger] TaskEntityDispatcher dispatcher)
{
    return dispatcher.DispatchAsync<CounterEntity>();
}

public class CounterEntity
{
    public int Value { get; set; }
    
    public void Add(int amount) => Value += amount;
    public int Get() => Value;
}

Informazioni di riferimento complete sulle API

Le tabelle seguenti forniscono un mapping completo tra le API di SDK dei processi di lavoro in-process 2.x e isolati.

API per il client

API del contesto di orchestrazione

API di entità

Modifiche comportamentali

• Serializzazione: il serializzatore predefinito è stato modificato da Newtonsoft.Json a System.Text.Json. Per altre informazioni, vedere Serializzazione e persistenza in Durable Functions.

• Rimozione del proxy di entità: CreateEntityProxy<T> e gli overload del delegato SignalEntityAsync<TEntityInterface>(Action<T>) tipizzato non sono disponibili nel processo di lavoro isolato. Chiamare Entities.CallEntityAsync o Entities.SignalEntityAsync direttamente con nomi di operazione basati su stringa anziché usare interfacce proxy tipate.
• WaitForCompletionOrCreateCheckStatusResponseAsync: il timeout parametro è stato rimosso. Usare invece un CancellationToken con un timeout di cancellazione.
• Operazioni tra hub di attività rimosse: gli overload in-process che accettano i parametri taskHubName e connectionName (in RaiseEventAsync, SignalEntityAsync e ReadEntityStateAsync) non sono disponibili in un processo di lavoro isolato. Sono supportate solo le operazioni dello stesso task hub.
• Operazioni batch per ID rimosse: gli overload GetStatusAsync(IEnumerable<string>) e PurgeInstanceHistoryAsync(IEnumerable<string>) non sono disponibili nel processo di lavoro isolato. Usare GetAllInstancesAsync con un filtro OrchestrationQuery o chiama GetInstanceAsync/PurgeInstanceAsync singolarmente.
• Cronologia di orchestrazione spostata: DurableOrchestrationStatus.History (l'elemento JArrayincorporato) non fa più parte dell'oggetto di stato. Usare l'API separata DurableTaskClient.GetOrchestrationHistoryAsync per recuperare la cronologia dell'orchestrazione.
• Parametri del costruttore DispatchAsync di entità: l'overload dei parametri del costruttore DispatchAsync<T>(params object[]) non è disponibile. Le classi di entità vengono attivate tramite l'inserimento delle dipendenze standard. Registra le dipendenze dell'entità in Program.cs.
• Modifiche al filtro delle query di entità: EntityQuery.EntityName viene sostituito da EntityQuery.InstanceIdStartsWithe EntityQuery.IncludeDeleted viene sostituito da EntityQuery.IncludeTransient.
• Modifica della firma CleanEntityStorageAsync: invece di (bool removeEmptyEntities, bool releaseOrphanedLocks, CancellationToken), la versione isolata accetta un oggetto con le proprietà RemoveEmptyEntities e ReleaseOrphanedLocks.
• Nuove API nel processo di lavoro isolato: DurableTaskClient.GetOrchestrationHistoryAsync e il metodo di estensione TaskOrchestrationContext.GetFunctionContext() sono disponibili nel processo di lavoro isolato, ma non hanno un equivalente nell'ambiente in-process.

Aggiornare local.settings.json

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
        "DURABLE_TASK_SCHEDULER_CONNECTION_STRING": "Endpoint=http://localhost:8080;Authentication=None"
    }
}

La modifica della chiave è FUNCTIONS_WORKER_RUNTIME da dotnet a dotnet-isolated.

Testare localmente

Avviare l'emulatore

docker run -d -p 8080:8080 -p 8082:8082 mcr.microsoft.com/dts/dts-emulator:latest

Eseguire l'applicazione di funzioni

func start

Verificare la funzionalità

Testare tutte le orchestrazioni, le attività e le entità per assicurarsi che funzionino correttamente:

1. Avviare un'orchestrazione con un trigger HTTP
2. Monitorare lo stato di orchestrazione
3. Verificare l'ordine di esecuzione dell'attività
4. Testare le operazioni di entità, se applicabile
5. Controllare i dati di telemetria di Application Insights

Distribuire in Azure

Consigliato: usare gli slot di distribuzione

Usare gli slot di distribuzione per minimizzare il downtime

1. Creare uno slot di staging per l'app per le funzioni.
2. Aggiornare la configurazione dello slot di staging:
   • Impostare FUNCTIONS_WORKER_RUNTIME su dotnet-isolated.
   • Aggiornare .NET versione dello stack, se necessario.
3. Distribuire il codice migrato nello slot di staging.
4. Eseguire un test approfondito nello slot di staging.
5. Eseguire lo scambio di slot per spostare le modifiche nell'ambiente di produzione.

Aggiornare le impostazioni dell'applicazione

Nel portale di Azure o tramite l'interfaccia della riga di comando:

az functionapp config appsettings set \
    --name <FUNCTION_APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --settings FUNCTIONS_WORKER_RUNTIME=dotnet-isolated

Aggiornare la configurazione dello stack

Se la destinazione è una versione .NET diversa:

az functionapp config set \
    --name <FUNCTION_APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --net-framework-version v8.0

Problemi comuni relativi alla migrazione

Problema: Errori di caricamento dell'assembly

Sintomo:Could not load file or assembly errori.

Soluzione: rimuovere tutti i Microsoft.Azure.WebJobs.* riferimenti al pacchetto e sostituirli con processi di lavoro isolati equivalenti.

Problema: Impossibile trovare l'attributo di associazione

Sintomo:The type or namespace 'QueueTrigger' could not be found

Soluzione: aggiungere il pacchetto di estensione appropriato e aggiornare le istruzioni using:

// Add using statement
using Microsoft.Azure.Functions.Worker;

// Install package
// dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues

Problema: IDurableOrchestrationContext non trovato

Sintomo:The type or namespace 'IDurableOrchestrationContext' could not be found

Soluzione: Sostituire con TaskOrchestrationContext:

using Microsoft.DurableTask;

[Function(nameof(MyOrchestrator))]
public static async Task MyOrchestrator([OrchestrationTrigger] TaskOrchestrationContext context)
{
    // ...
}

Problema: differenze di serializzazione JSON

Sintomo: Errori di serializzazione o formati di dati imprevisti

Soluzione: Il modello isolato utilizza System.Text.Json per impostazione predefinita. Configurare la serializzazione in Program.cs:

var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services => {
        services.Configure<JsonSerializerOptions>(options => {
            options.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
        });
    })
    .Build();

Per usare invece Newtonsoft.Json:

services.Configure<WorkerOptions>(options => {
    options.Serializer = new NewtonsoftJsonObjectSerializer();
});

Problema: Migrazione delle impostazioni di serializzazione personalizzate

Sintomo: è stato usato IMessageSerializerSettingsFactory nel modello in-process per personalizzare la serializzazione JSON per input, output o stato dell'entità di orchestrazione ed è necessario l'elemento equivalente nel processo di lavoro isolato.

Soluzione: L'interfaccia IMessageSerializerSettingsFactory non è disponibile nel worker isolato. Configurare invece il serializzatore a livello di processo di lavoro in Program.cs:

Prima di (In-Process):

// Startup.cs
[assembly: FunctionsStartup(typeof(MyStartup))]
public class MyStartup : FunctionsStartup
{
    public override void Configure(IFunctionsHostBuilder builder)
    {
        builder.Services.AddSingleton<IMessageSerializerSettingsFactory, CustomSerializerSettingsFactory>();
    }
}

Dopo (Lavoratore Isolato)

// Program.cs
var host = new HostBuilder()
    .ConfigureFunctionsWebApplication()
    .ConfigureServices(services =>
    {
        services.Configure<WorkerOptions>(options =>
        {
            var settings = new JsonSerializerSettings
            {
                TypeNameHandling = TypeNameHandling.None,
                DateFormatHandling = DateFormatHandling.IsoDateFormat,
            };
            options.Serializer = new NewtonsoftJsonObjectSerializer(settings);
        });
    })
    .Build();

Checklist

Usare questo elenco di controllo per garantire una migrazione completa:

• File di progetto aggiornato con <OutputType>Exe</OutputType>
• Sostituito Microsoft.NET.Sdk.Functions con i pacchetti di lavoro
• Sostituito Microsoft.Azure.WebJobs.Extensions.DurableTask con un pacchetto isolato
• Creato Program.cs con la configurazione dell'host
• Classe rimossa FunctionsStartup (se presente)
• Aggiornati tutti [FunctionName] a [Function]
• Sostituito IDurableOrchestrationContext con TaskOrchestrationContext
• Sostituito IDurableOrchestrationClient con DurableTaskClient
• Registrazione aggiornata per l'uso di DI o FunctionContext
• Aggiornato il runtime di local.settings.json con dotnet-isolated
• Sono state rimosse tutte le istruzioni using di Microsoft.Azure.WebJobs.*
• Sono state aggiunte istruzioni using di Microsoft.Azure.Functions.Worker
• Sostituito CreateEntityProxy<T> con chiamate dirette CallEntityAsync/SignalEntityAsync
• Sostituzione degli overload delle operazioni tra hub di attività (se in uso)
• Sostituite le chiamate batch GetStatusAsync/PurgeInstanceHistoryAsync per ID con chiamate singole o basate su filtro
• Accesso migrato DurableOrchestrationStatus.History a GetOrchestrationHistoryAsync
• Parametri del costruttore DispatchAsync di entità aggiornati per l'uso dell'inserimento delle dipendenze
• Tutte le funzioni sono state testate in locale
• Distribuito nello slot di staging e verificato
• Scambiato in produzione

Passaggi successivi

• Panoramica del processo di lavoro isolato di .NET
• Panoramica di Durable Functions per il processo di lavoro .NET isolato
• Durable Functions modelli e concetti tecnici

Risorse aggiuntive

• Guida ufficiale alla migrazione Microsoft
• Differenze del modello di lavoro isolato
• Guida agli unit test per Durable Functions (ambiente isolato)
• Serializzazione e persistenza in Durable Functions
• Controllo delle versioni in Durable Functions
• Distribuzione senza tempi di inattività per Durable Functions
• Configurare il Schedulatore di Attività Durevoli
• Esempi di codice per Durable Functions