Condividi tramite

Eseguire la migrazione delle app dalla versione 1.x alla versione 4.x di Funzioni di Azure

  • Articolo

Importante

Java non è supportato dalla versione 1.x del runtime di Funzioni di Azure. È possibile che si stia cercando di eseguire la migrazione di un'app Java dalla versione 3.x alla versione 4.x. Se si esegue la migrazione di un'app per le funzioni 1.x, selezionare C# o JavaScript come indicato sopra.

Importante

TypeScript non è supportato dalla versione 1.x del runtime di Funzioni di Azure. È possibile che si stia cercando di eseguire la migrazione di un'app TypeScript dalla versione 3.x alla versione 4.x. Se si esegue la migrazione di un'app per le funzioni 1.x, selezionare C# o JavaScript come indicato sopra.

Importante

PowerShell non è supportato dalla versione 1.x del runtime di Funzioni di Azure. È possibile che si stia cercando di eseguire la migrazione di un'app PowerShell dalla versione 3.x alla versione 4.x. Se si esegue la migrazione di un'app per le funzioni 1.x, selezionare C# o JavaScript come indicato sopra.

Importante

Python non è supportato dalla versione 1.x del runtime di Funzioni di Azure. È possibile che si stia cercando di eseguire la migrazione di un'app Python dalla versione 3.x alla versione 4.x. Se si esegue la migrazione di un'app per le funzioni 1.x, selezionare C# o JavaScript come indicato sopra.

Importante

Il supporto terminerà per la versione 1.x del runtime di Funzioni di Azure il 14 settembre 2026. È preferibile eseguire la migrazione delle app alla versione 4.x seguendo le istruzioni riportate in questo articolo.

Questo articolo illustra il processo di migrazione sicura di un'app per le funzioni da eseguire nella versione 4.x del runtime di Funzioni. Poiché le istruzioni di migrazione del progetto dipendono dal linguaggio, accertarsi di scegliere il linguaggio di sviluppo dal selettore, come riportato in cima all’articolo.

Se si esegue la versione 1.x del runtime nell'hub di Azure Stack, vedere prima Considerazioni per l'hub di Azure Stack.

Identificare le app per le funzioni di cui eseguire la migrazione

Usare lo script PowerShell seguente per generare un elenco di app per le funzioni nella sottoscrizione attualmente destinate alla versione 1.x:

$Subscription = '<YOUR SUBSCRIPTION ID>' 

Set-AzContext -Subscription $Subscription | Out-Null

$FunctionApps = Get-AzFunctionApp

$AppInfo = @{}

foreach ($App in $FunctionApps)
{
     if ($App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"] -like '*1*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

Scegliere la versione di .NET di destinazione

Nella versione 1.x del runtime di Funzioni, l'app per le funzioni C# è destinata a .NET Framework.

Quando si esegue la migrazione dell'app per le funzioni, è possibile scegliere la versione di destinazione di .NET. È possibile aggiornare un progetto C# a una delle versioni seguenti di .NET supportate dalla versione 4.x di Funzioni:

Versione di .NET Tipo di rilascio Criteri di supporto ufficiali di .NET Modello di processo di Funzioni1,2
.NET 8 LTS (fine del supporto 10 novembre 2026) Modello di lavoro isolato,
Modello In-Process2,3
.NET 6 LTS (fine del supporto 12 novembre 2024) Modello di lavoro isolato,
Modello In-Process2
.NET Framework 4.8 Vedere i criteri Modello di lavoro isolato

1 Il modello di lavoro isolato supporta le versioni LTS (Long Term Support) e STS (Standard Term Support) di .NET, nonché .NET Framework. Il modello In-Process supporta solo i rilasci LTS di .NET che terminano con .NET 8. Per un confronto completo delle caratteristiche e delle funzionalità tra i due modelli, vedere Differenze tra il processo di lavoro In-Process e isolato per Funzioni di Azure .NET.

2 Il supporto per il modello In-Process terminerà il 10 novembre 2026. Per altre informazioni, vedere questo annuncio relativo al supporto. Per la prosecuzione del supporto completo, eseguire la migrazione delle app al modello di lavoro isolato.

3 La scelta di .NET 8 con il modello In-Process non è ancora abilitata per Linux, per le app ospitate in ambienti del servizio app o per le app nei cloud sovrani. Gli aggiornamenti verranno comunicati in questo thread di monitoraggio in GitHub.

Suggerimento

A meno che l'app non dipenda da una libreria o da un'API disponibile solo per .NET Framework, è preferibile eseguire l'aggiornamento a .NET 8 nel modello di lavoro isolato. Molte app nella versione 1.x sono destinate solo a .NET Framework perché era disponibile al momento della creazione delle app. Sono disponibili funzionalità aggiuntive per le versioni più recenti di .NET e se l'app non è costretta a rimanere in .NET Framework a causa di una dipendenza, scegliere una versione più recente. .NET 8 è la versione completamente rilasciata con la finestra di supporto più lunga da .NET.

Anche se si può scegliere di usare il modello In-Process, tale scelta è sconsigliata se può essere evitata. Il supporto per il modello In-Process terminerà il 10 novembre 2026, quindi sarà necessario passare al modello di lavoro isolato prima di tale data. In tal modo, durante la migrazione alla versione 4.x si ridurrà il lavoro totale richiesto e il modello di lavoro isolato offrirà all'app ulteriori vantaggi, inclusa la possibilità di scegliere più facilmente le versioni future di .NET. Se si passa al modello di lavoro isolato, Assistente aggiornamento .NET può anche gestire molte modifiche necessarie al codice.

Questa guida non presenta esempi specifici per .NET 6. Se è necessario scegliere tale versione, è possibile adattare gli esempi di .NET 8.

Preparare la migrazione

Se non è stato ancora fatto, identificare l'elenco di app che richiedono la migrazione nella propria sottoscrizione di Azure corrente tramite Azure PowerShell.

Prima di eseguire la migrazione di un'app alla versione 4.x del runtime di Funzioni, è necessario eseguire le attività seguenti:

  1. Esaminare l'elenco delle modifiche del comportamento dopo la versione 1.x. Anche la migrazione dalla versione 1.x alla versione 4.x può influire sulle associazioni.
  2. Completare i passaggi descritti in Eseguire la migrazione di un progetto locale per eseguire la migrazione di un progetto locale alla versione 4.x.
  3. Dopo la migrazione del progetto, testare l’app in locale usando la versione 4.x di Azure Functions Core Tools.
  4. Aggiornare l'app per le funzioni in Azure alla nuova versione. Se è necessario ridurre al minimo il tempo di inattività, considerare l’uso di uno slot di staging per testare e verificare l’app migrata in Azure nella nuova versione del runtime. È possibile, quindi, distribuire l'app con le impostazioni della versione aggiornata nello slot di produzione. Per altre informazioni, vedere Aggiornamento tramite slot.
  5. Pubblicare il progetto migrato nell'app per le funzioni aggiornata.

Quando si usa Visual Studio per pubblicare un progetto versione 4.x in un'app per le funzioni esistente con una versione precedente, viene chiesto di consentire a Visual Studio di aggiornare l'app per le funzioni alla versione 4.x durante la distribuzione. Questo aggiornamento usa lo stesso processo definito in Aggiornamento senza slot.

Eseguire la migrazione di un progetto locale

Le sezioni seguenti descrivono gli aggiornamenti che è necessario apportare ai file di progetto C# per poterli eseguire in una delle versioni supportate di .NET in Funzioni versione 4.x. Gli aggiornamenti visualizzati sono quelli comuni alla maggior parte dei progetti. Il codice del progetto potrebbe richiedere aggiornamenti non menzionati in questo articolo, specialmente quando si usano pacchetti NuGet personalizzati.

La migrazione di un'app per le funzioni C# dalla versione 1.x alla versione 4.x del runtime di Funzioni richiede di apportare modifiche al codice del progetto. Molte di queste modifiche sono il risultato di modifiche apportate al linguaggio C# e alle API .NET.

Scegliere la scheda corrispondente alla versione di destinazione di .NET e al modello di processo desiderato (processo di lavoro In-Process o isolato).

Suggerimento

Se si passa a una versione LTS o STS di .NET usando il modello di lavoro isolato, è possibile usare l’Assistente aggiornamento .NET per apportare automaticamente molte delle modifiche indicate nelle sezioni seguenti.

File di progetto

L'esempio seguente è un file di progetto .csproj eseguito nella versione 1.x:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v1</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="1.0.24" />
  </ItemGroup>
  <ItemGroup>
    <Reference Include="Microsoft.CSharp" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

Utilizzare una delle procedure seguenti per aggiornare questo file XML da eseguire in Funzioni versione 4.x:

Questi passaggi presuppongono un progetto C# locale; se l'app, invece, usa script C# (file .csx), è necessaria la conversione al modello di progetto prima di continuare.

Nel file di progetto XML .csproj è necessario apportare le modifiche seguenti:

  1. Impostare il valore di PropertyGroup.Da TargetFramework a net8.0.

  2. Impostare il valore di PropertyGroup.Da AzureFunctionsVersion a v4.

  3. Aggiungere l'elemento OutputType seguente a PropertyGroup:

    <OutputType>Exe</OutputType>

  4. Nell’elenco ItemGroupPackageReference, sostituire il riferimento al pacchetto a Microsoft.NET.Sdk.Functions con i riferimenti seguenti:

      <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.ApplicationInsights.WorkerService" Version="2.22.0" />
  <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />

    Prendere nota di eventuali riferimenti ad altri pacchetti negli spazi dei nomi Microsoft.Azure.WebJobs.*. Questi pacchetti verranno sostituiti in un passaggio successivo.

  5. Aggiungere il nuovo ItemGroup seguente:

    <ItemGroup>
  <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
</ItemGroup>

Dopo aver apportato queste modifiche, il progetto aggiornato sarà simile all'esempio seguente:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <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.ApplicationInsights.WorkerService" Version="2.22.0" />
    <PackageReference Include="Microsoft.Azure.Functions.Worker.ApplicationInsights" Version="1.2.0" />
    <!-- Other packages may also be in this list -->
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
  <ItemGroup>
    <Using Include="System.Threading.ExecutionContext" Alias="ExecutionContext"/>
  </ItemGroup>
</Project>

Modifiche ai pacchetti e agli spazi dei nomi

In base al modello a cui si esegue la migrazione, potrebbe essere necessario aggiornare o modificare i pacchetti a cui si fa riferimento l'applicazione. Quando si adottano i pacchetti di destinazione, è necessario aggiornare lo spazio dei nomi delle istruzioni using e alcuni tipi a cui si fa riferimento. È possibile visualizzare l'effetto di queste modifiche dello spazio dei nomi nelle istruzioni using negli esempi di modelli di trigger HTTP più avanti in questo articolo.

Se non è stato ancora fatto, aggiornare il progetto per fare riferimento alle versioni stabili più recenti di:

A seconda dei trigger e delle associazioni usate dall'app, è possibile che l'app debba fare riferimento a un set diverso di pacchetti. La tabella seguente illustra le sostituzioni per alcune estensioni più usate:

Scenario Modifiche ai riferimenti del pacchetto
Trigger timer Aggiunta
Microsoft.Azure.Functions.Worker.Extensions.Timer
Associazioni di archiviazione Sostituzione
Microsoft.Azure.WebJobs.Extensions.Storage
con
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues,
Microsoft.Azure.Functions.Worker.Extensions.Tables
Associazioni di BLOB Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Associazioni di code Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Associazioni di tabelle Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Tables
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.Tables
Associazioni di Cosmos DB Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.CosmosDB
e/o
Microsoft.Azure.WebJobs.Extensions.DocumentDB
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Associazioni di bus di servizio Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.ServiceBus
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Associazioni di Hub eventi Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.EventHubs
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Associazioni di Griglia di eventi Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.EventGrid
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Associazioni del Servizio SignalR Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.SignalRService
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Funzioni durevoli Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.DurableTask
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Funzioni durevoli
(provider di archiviazione SQL)		 Sostituire i riferimenti a
Microsoft.DurableTask.SqlServer.AzureFunctions
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Funzioni durevoli
(provider di archiviazione Netherite)		 Sostituire i riferimenti a
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Associazioni SendGrid Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.SendGrid
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Associazioni di Kafka Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Kafka
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Associazioni di RabbitMQ Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
con versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Inserimento delle dipendenze
e configurazione di avvio		 Rimuovere i riferimenti a
Microsoft.Azure.Functions.Extensions
(Il modello di lavoro isolato fornisce questa funzionalità per impostazione predefinita.)

Per un elenco completo delle estensioni da considerare, vedere Associazioni supportate e consultare la documentazione di ogni estensione per le istruzioni complete sull'installazione per il modello di processo isolato. Accertarsi di installare la versione stabile più recente di ogni pacchetto di destinazione.

Suggerimento

Eventuali modifiche alle versioni delle estensioni durante questo processo potrebbero richiedere anche l'aggiornamento del file host.json. Accertarsi di leggere la documentazione di ogni estensione usata. Ad esempio, l'estensione del bus di servizio presenta modifiche di rilievo nella struttura tra le versioni 4.x e 5.x. Per altre informazioni, vedere Associazioni del bus di servizio di Azure per Funzioni di Azure.

L'applicazione del modello di lavoro isolato non deve fare riferimento ad alcun pacchetto negli spazi dei nomi Microsoft.Azure.WebJobs.* o Microsoft.Azure.Functions.Extensions. Se esistono riferimenti rimanenti a questi pacchetti, devono essere rimossi.

Suggerimento

L'app potrebbe anche dipendere da tipi Azure SDK, come parte dei trigger e delle associazioni o come dipendenza autonoma. È consigliabile sfruttare questa opportunità per aggiornare anche questi elementi. Le versioni più recenti delle estensioni di Funzioni funzionano con le versioni più recenti di Azure SDK per .NET, per le quali quasi tutti i pacchetti sono il modulo Azure.*.

Le associazioni di Hub di notifica e App per dispositivi mobili sono supportate solo nella versione 1.x del runtime. Quando si esegue l'aggiornamento alla versione 4.x del runtime, è necessario rimuovere queste associazioni preferendo l’uso diretto di questi servizi tramite i relativi SDK.

File program.cs

Nella maggior parte dei casi, la migrazione richiede l’aggiunta del file di program.cs seguente al 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();

Questo esempio include l’integrazione di ASP.NETCore per migliorare le prestazioni e fornire un modello di programmazione familiare quando l'app usa trigger HTTP. Se non si intende usare trigger HTTP, è possibile sostituire la chiamata a ConfigureFunctionsWebApplication con una chiamata a ConfigureFunctionsWorkerDefaults. In tal caso, è possibile rimuovere il riferimento a Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore dal file di progetto. Tuttavia, per ottenere prestazioni ottimali anche per le funzioni con altri tipi di trigger, è preferibile mantenere FrameworkReference con ASP.NET Core.

Il file Program.cs sostituirà qualunque file con l'attributo FunctionsStartup, che generalmente è un file Startup.cs. Nei punti in cui il codice FunctionsStartup fa riferimento a IFunctionsHostBuilder.Services, invece, è possibile aggiungere istruzioni all'interno del metodo .ConfigureServices() di HostBuilder in Program.cs. Per altre informazioni sull'uso di Program.cs, vedere Avvio e configurazione nella guida al modello di lavoro isolato.

Gli esempi di Program.cs predefiniti precedenti includono la configurazione dell’integrazione di Application Insights per il modello di lavoro isolato. In Program.cs è necessario configurare anche tutti i filtri di log che devono essere applicati ai log provenienti dal codice nel progetto. Nel modello di lavoro isolato il file host.json controlla solo gli eventi emessi dal runtime dell'host di Funzioni. Se non si configurano regole di filtro in Program.cs, è possibile che vengano visualizzate differenze nei livelli di log presenti per varie categorie nei dati di telemetria.

Anche se è possibile registrare origini di configurazione personalizzate come parte di HostBuilder, tenere presente che si applicano in modo analogo solo al codice nel progetto. La configurazione dei trigger e delle associazioni è necessaria anche per la piattaforma e deve essere effettuata tramite le funzionalità di impostazioni dell’applicazione, riferimenti a Key Vault o riferimenti alla Configurazione app.

Dopo aver spostato tutti gli elementi da qualunque FunctionsStartup esistente nel file Program.cs, è possibile eliminare l'attributo FunctionsStartup e la classe a cui è stato applicato.

File host.json

Le impostazioni nel file host.json si applicano a livello di app per le funzioni, sia in locale che in Azure. Nella versione 1.x, il file host.json è vuoto o contiene alcune impostazioni applicabili a tutte le funzioni nell'app per le funzioni. Per altre informazioni, vedere Host.json v1. Se il file host.json include valori di impostazione, esaminare il formato host.json v2 per rilevare eventuali modifiche.

Per l'esecuzione nella versione 4.x, è necessario aggiungere "version": "2.0" al file di host.json. È preferibile anche considerare l’aggiunta di logging alla configurazione, come negli esempi seguenti:

{
    "version": "2.0",
    "logging": {
        "applicationInsights": {
            "samplingSettings": {
                "isEnabled": true,
                "excludedTypes": "Request"
            },
            "enableLiveMetricsFilters": true
        }
    }
}

Il file host.json controlla solo la registrazione dal runtime dell'host di Funzioni e nel modello di lavoro isolato alcuni di questi log provengono direttamente dall'applicazione, offrendo un maggiore controllo. Per informazioni dettagliate su come filtrare questi log, vedere Gestione dei livelli di log nel modello di lavoro isolato.

File local.settings.json

Il file local.settings.json è utilizzato solo con l’esecuzione in locale. Per informazioni, vedere File di impostazioni locali. Nella versione 1.x, il file local.settings.json include solo due valori obbligatori:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "AzureWebJobsDashboard": "AzureWebJobsStorageConnectionStringValue"
    }
}

Quando si esegue la migrazione alla versione 4.x, assicurarsi che il file local.settings.json includa almeno gli elementi seguenti:

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated"
    }
}

Nota

Quando si esegue la migrazione dall'esecuzione In-Process all'esecuzione in un processo di lavoro isolato, è necessario modificare il valore FUNCTIONS_WORKER_RUNTIME in "dotnet-isolated".

Modifiche del nome classe

Alcune classi chiave cambiano i nomi tra la versione 1.x e la versione 4.x. Queste modifiche sono il risultato di modifiche delle API .NET o delle differenze tra processo di lavoro In-Process e isolato. La tabella seguente indica le classi .NET chiave usate da Funzioni che potrebbero cambiare durante la migrazione:

Versione 1.x .NET 8
FunctionName (attributo) Function (attributo)
TraceWriter ILogger<T>, ILogger
HttpRequestMessage HttpRequestData, HttpRequest (usando l’integrazione ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (usando l’integrazione ASP.NET Core)

Potrebbero verificarsi differenze tra i nomi classe anche nelle associazioni. Per altre informazioni, vedere gli articoli di riferimento per le associazioni specifiche.

Altre modifiche al codice

In questa sezione vengono evidenziate altre modifiche al codice da considerare durante l'esecuzione della migrazione. Queste modifiche non sono necessarie per tutte le applicazioni, ma è preferibile valutare se sono pertinenti per gli scenari in uso. Accertarsi di controllare le Modifiche del comportamento dopo la versione 1.x per ulteriori modifiche che potrebbe essere necessario apportare al progetto.

Serializzazione JSON

Per impostazione predefinita, il modello di lavoro isolato usa System.Text.Json per la serializzazione JSON. Per personalizzare le opzioni del serializzatore o passare a JSON.NET (Newtonsoft.Json), vedere queste istruzioni.

Filtri e livelli di log di Application Insights

I log possono essere inviati ad Application Insights sia dal runtime dell'host di Funzioni che dal codice nel progetto. host.json consente di configurare regole per la registrazione dell'host, ma per controllare i log provenienti dal codice è necessario configurare regole di filtro come parte di Program.cs. Per informazioni dettagliate su come filtrare questi log, vedere Gestione dei livelli di log nel modello di lavoro isolato.

Modello di trigger HTTP

La maggior parte delle modifiche al codice tra la versione 1.x e la versione 4.x è visibile nelle funzioni attivate da HTTP. Il modello di trigger HTTP per la versione 1.x è simile all’esempio seguente:

using System.Linq;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Host;

namespace Company.Function
{
    public static class HttpTriggerCSharp
    {
        [FunctionName("HttpTriggerCSharp")]
        public static async Task<HttpResponseMessage> 
            Run([HttpTrigger(AuthorizationLevel.AuthLevelValue, "get", "post", 
            Route = null)]HttpRequestMessage req, TraceWriter log)
        {
            log.Info("C# HTTP trigger function processed a request.");

            // parse query parameter
            string name = req.GetQueryNameValuePairs()
                .FirstOrDefault(q => string.Compare(q.Key, "name", true) == 0)
                .Value;

            if (name == null)
            {
                // Get request body
                dynamic data = await req.Content.ReadAsAsync<object>();
                name = data?.name;
            }

            return name == null
                ? req.CreateResponse(HttpStatusCode.BadRequest, 
                    "Please pass a name on the query string or in the request body")
                : req.CreateResponse(HttpStatusCode.OK, "Hello " + name);
        }
    }
}

Nella versione 4.x, il modello di trigger HTTP è simile all'esempio seguente:

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
using Microsoft.Extensions.Logging;

namespace Company.Function
{
    public class HttpTriggerCSharp
    {
        private readonly ILogger<HttpTriggerCSharp> _logger;

        public HttpTriggerCSharp(ILogger<HttpTriggerCSharp> logger)
        {
            _logger = logger;
        }

        [Function("HttpTriggerCSharp")]
        public IActionResult Run(
            [HttpTrigger(AuthorizationLevel.Function, "get")] HttpRequest req)
        {
            _logger.LogInformation("C# HTTP trigger function processed a request.");

            return new OkObjectResult($"Welcome to Azure Functions, {req.Query["name"]}!");
        }
    }
}

Per aggiornare un progetto a Funzioni di Azure 4.x:

  1. Aggiornare l'installazione locale di Azure Functions Core Tools alla versione 4.x.

  2. Passare a una delle Versioni di Node.js supportate nella versione 4.x.

  3. Aggiungere gli elementi version e extensionBundle al file host.json, in modo l’aspetto sia simile all'esempio seguente:

    {
    "version": "2.0",
    "extensionBundle": {
        "id": "Microsoft.Azure.Functions.ExtensionBundle",
        "version": "[3.3.0, 4.0.0)"
    }
}

    L'elemento extensionBundle è necessario perché dopo la versione 1.x, le associazioni vengono mantenute come pacchetti esterni. Per altre informazioni, vedere Bundle di estensioni.

  4. Aggiornare il file local.settings.json in modo che contenga almeno gli elementi seguenti:

    {
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "UseDevelopmentStorage=true",
        "FUNCTIONS_WORKER_RUNTIME": "node"
    }
}

    L'impostazione AzureWebJobsStorage può essere l'emulatore di archiviazione Azurite o un account di archiviazione di Azure effettivo. Per altre informazioni, vedere Emulatore di archiviazione locale.

Aggiornare un'app per le funzioni in Azure

È necessario aggiornare il runtime dell'host dell'app per le funzioni in Azure alla versione 4.x prima di pubblicare il progetto migrato. La versione di runtime usata dall'host di Funzioni è controllata dall'impostazione dell'applicazione FUNCTIONS_EXTENSION_VERSION, ma in alcuni casi è necessario aggiornare anche altre impostazioni. Sia le modifiche al codice che le modifiche apportate alle impostazioni dell'applicazione richiedono il riavvio dell'app per le funzioni.

Il modo più semplice consiste nell’aggiornamento senza slot e nella ripubblicazione del progetto dell'app. È anche possibile ridurre al minimo il tempo di inattività nell'app e semplificare il rollback tramite l’l'aggiornamento tramite slot.

Aggiornamento senza slot

Il modo più semplice per eseguire l'aggiornamento a v4.x consiste nel configurare l'impostazione dell'applicazione FUNCTIONS_EXTENSION_VERSION su ~4 nell'app per le funzioni in Azure. È necessario seguire una procedura diversa in un sito con slot.

az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

È necessario anche configurare un'altra impostazione, che varia tra Windows e Linux.

Con l’esecuzione in Windows, è necessario anche abilitare .NET 6.0, richiesto dalla versione 4.x del runtime.

az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

.NET 6 è necessario per le app per le funzioni in qualunque linguaggio in esecuzione in Windows.

In questo esempio, sostituire <APP_NAME> e <RESOURCE_GROUP_NAME> rispettivamente con il nome dell'app per le funzioni e il nome del gruppo di risorse.

A questo punto, è possibile ripubblicare il progetto dell'app di cui è stata eseguita la migrazione per l'esecuzione nella versione 4.x.

Aggiornamento tramite slot

L'uso di slot di distribuzione rappresenta una scelta efficace per aggiornare l'app per le funzioni al runtime v4.x da una versione precedente. Usando uno slot di staging, è possibile eseguire l'app nella nuova versione del runtime nello slot di staging e passare alla produzione dopo la verifica. Gli slot consentono anche di ridurre al minimo i tempi di inattività durante l'aggiornamento. Se è necessario ridurre al minimo i tempi di inattività, seguire la procedura descritta in Aggiornamento con il minimo tempo di inattività.

Dopo aver verificato l'app nello slot aggiornato, è possibile scambiare l'app e le nuove impostazioni della versione nell'ambiente di produzione. Questo scambio richiede l'impostazione WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 nello slot di produzione. La modalità con cui viene aggiunta questa impostazione influisce sul tempo di inattività necessario per l'aggiornamento.

Aggiornamento standard

Se l'app per le funzioni abilitata per slot può gestire il tempo di inattività di un riavvio completo, è possibile aggiornare l'impostazione WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS direttamente nello slot di produzione. Poiché la modifica di questa impostazione direttamente nello slot di produzione causa un riavvio che influisce sulla disponibilità, considerare l'esecuzione di questa modifica in periodi di traffico ridotto. A questo punto, è possibile scambiare la versione aggiornata dallo slot di staging.

Il cmdlet PowerShell Update-AzFunctionAppSetting attualmente non supporta gli slot. È necessario usare l'interfaccia della riga di comando di Azure o il portale di Azure.

  1. Usare il comando seguente per impostare WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 nello slot di produzione:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0  -g <RESOURCE_GROUP_NAME>  -n <APP_NAME>

    In questo esempio, sostituire <APP_NAME> e <RESOURCE_GROUP_NAME> rispettivamente con il nome dell'app per le funzioni e il nome del gruppo di risorse. Questo comando causa il riavvio dell'app in esecuzione nello slot di produzione.

  2. Usare il comando seguente per impostare anche WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS nello slot di staging:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  3. Usare il comando seguente per modificare FUNCTIONS_EXTENSION_VERSION e aggiornare lo slot di staging alla nuova versione del runtime:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  4. La versione 4.x del runtime di Funzioni richiede .NET 6 in Windows. In Linux, le app .NET devono anche eseguire l'aggiornamento a .NET 6. Usare il comando seguente in modo che il runtime possa essere eseguito in .NET 6:

    Con l’esecuzione in Windows, è necessario anche abilitare .NET 6.0, richiesto dalla versione 4.x del runtime.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 è necessario per le app per le funzioni in qualunque linguaggio in esecuzione in Windows.

    In questo esempio, sostituire <APP_NAME> e <RESOURCE_GROUP_NAME> rispettivamente con il nome dell'app per le funzioni e il nome del gruppo di risorse.

  5. Se il progetto del codice richiede aggiornamenti per l'esecuzione nella versione 4.x, distribuire ora tali aggiornamenti nello slot di staging.

  6. Accertarsi che l'app per le funzioni venga eseguita correttamente nell'ambiente di staging aggiornato prima dello scambio.

  7. Usare il comando seguente per scambiare lo slot di staging aggiornato in produzione:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Aggiornamento con il minimo tempo di inattività

Per ridurre al minimo il tempo di inattività nell'app di produzione, è possibile scambiare l'impostazione WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS dallo slot di staging in produzione. Successivamente, è possibile scambiare la versione aggiornata da uno slot di staging preriscaldato.

  1. Usare il comando seguente per impostare WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 nello slot di staging:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  2. Usare i comandi seguenti per scambiare lo slot con la nuova impostazione nell'ambiente di produzione e ripristinare contemporaneamente l'impostazione della versione nello slot di staging.

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production
az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~3 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    È possibile che vengano visualizzati errori nello slot di staging durante il periodo di tempo tra lo scambio e la versione del runtime da ripristinare in staging. Questo errore può verificarsi perché la presenza di WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 solo in staging durante uno scambio rimuove l'impostazione FUNCTIONS_EXTENSION_VERSION in staging. Senza l'impostazione della versione, lo slot è in uno stato non valido. L'aggiornamento della versione nello slot di staging subito dopo lo scambio dovrebbe riportare lo slot in uno stato valido e chiamare il rollback delle modifiche, se necessario. Tuttavia, qualunque rollback dello scambio richiede anche la rimozione diretta di WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dalla produzione prima dello scambio, per evitare che gli errori in staging si ripresentino in produzione. Questa modifica nell'impostazione di produzione causa un riavvio.

  3. Usare il comando seguente per impostare nuovamente WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 nello slot di staging:

    az functionapp config appsettings set --settings WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

    A questo punto, entrambi gli slot hanno WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 impostato.

  4. Usare il comando seguente per modificare FUNCTIONS_EXTENSION_VERSION e aggiornare lo slot di staging alla nuova versione del runtime:

    az functionapp config appsettings set --settings FUNCTIONS_EXTENSION_VERSION=~4 -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME>

  5. La versione 4.x del runtime di Funzioni richiede .NET 6 in Windows. In Linux, le app .NET devono anche eseguire l'aggiornamento a .NET 6. Usare il comando seguente in modo che il runtime possa essere eseguito in .NET 6:

    Con l’esecuzione in Windows, è necessario anche abilitare .NET 6.0, richiesto dalla versione 4.x del runtime.

    az functionapp config set --net-framework-version v6.0 -g <RESOURCE_GROUP_NAME> -n <APP_NAME>

    .NET 6 è necessario per le app per le funzioni in qualunque linguaggio in esecuzione in Windows.

    In questo esempio, sostituire <APP_NAME> e <RESOURCE_GROUP_NAME> rispettivamente con il nome dell'app per le funzioni e il nome del gruppo di risorse.

  6. Se il progetto del codice richiede aggiornamenti per l'esecuzione nella versione 4.x, distribuire ora tali aggiornamenti nello slot di staging.

  7. Accertarsi che l'app per le funzioni venga eseguita correttamente nell'ambiente di staging aggiornato prima dello scambio.

  8. Usare il comando seguente per scambiare lo slot di staging aggiornato e preriscaldato in produzione:

    az functionapp deployment slot swap -g <RESOURCE_GROUP_NAME>  -n <APP_NAME> --slot <SLOT_NAME> --target-slot production

Modifiche del comportamento dopo la versione 1.x

Questa sezione illustra in dettaglio le modifiche apportate dopo la versione 1.x nei comportamenti sia di trigger che di associazioni, nonché nelle principali funzionalità e comportamenti di Funzioni.

Modifiche apportate a trigger e binding

A partire dalla versione 2.x, è necessario installare le estensioni per specifici trigger e associazioni usati dalle funzioni nell'app. L'unica eccezione sono i trigger HTTP e Timer, che non richiedono un'estensione. Per altre informazioni, vedere Registrare le estensioni delle associazioni.

Sono state apportate alcune modifiche anche in function.json o negli attributi della funzione tra le versioni. Ad esempio, la proprietà path dell'Hub eventi ora è eventHubName. Vedere la tabella di binding esistente per collegamenti alla documentazione per ogni binding.

Modifiche nelle funzioni e nella funzionalità

Alcune funzionalità sono state rimosse, aggiornate o sostituite dopo la versione 1.x. Questa sezione illustra nel dettaglio le modifiche riscontrabili nelle versioni successive dopo aver usato la versione 1.x.

Nella versione 2.x sono state apportate le modifiche seguenti:

  • Le chiavi per chiamare gli endpoint HTTP vengono sempre archiviate con crittografia in Archiviazione BLOB di Azure. Nella versione 1.x, le chiavi erano memorizzate in File di Azure per impostazione predefinita. Quando si esegue la migrazione di un'app dalla versione 1.x alla versione 2.x, i segreti esistenti in File di Azure vengono reimpostati.

  • La versione 2.x del runtime non include supporto incorporato per i provider di webhook. Questa modifica è stata apportata per migliorare le prestazioni. È comunque possibile usare i trigger HTTP come endpoint per i webhook.

  • Per migliorare il monitoraggio, il dashboard di Processi Web nel portale, che usa l'impostazione AzureWebJobsDashboard, è stato sostituito con Azure Application Insights, che usa l'impostazione APPINSIGHTS_INSTRUMENTATIONKEY. Per altre informazioni, vedere Monitorare Funzioni di Azure.

  • Tutte le funzioni in un'app per le funzioni devono condividere lo stesso linguaggio. Quando si crea un'app per le funzioni, è necessario scegliere uno stack di runtime per l'app. Lo stack di runtime viene specificato dal valore FUNCTIONS_WORKER_RUNTIME nelle impostazioni dell'applicazione. Questo requisito è stato aggiunto per migliorare tempi di avvio e footprint. In caso di sviluppo in locale, è necessario includere anche questa impostazione nel file local.settings.json.

  • Il timeout predefinito per le funzioni in un piano di servizio app è ora di 30 minuti. È possibile riportare manualmente il timeout al valore illimitato mediante l'impostazione functionTimeout in host.json.

  • Per impostazione predefinita vengono implementate limitazioni di concorrenza HTTP per le funzioni del piano A consumo, con un valore predefinito di 100 richieste simultanee per istanza. È possibile modificare questo comportamento nell'impostazione maxConcurrentRequests del file host.json.

  • A causa delle limitazioni di .NET Core, il supporto per le funzioni script F# (file .fsx) è stato rimosso. Le funzioni F# compilate (.fs) sono ancora supportate.

  • Il formato dell’URL dei webhook del trigger di Griglia di eventi è stato modificato per seguire questo modello: https://{app}/runtime/webhooks/{triggerName}.

  • I nomi di alcune metriche personalizzate predefinite sono stati modificati dopo la versione 1.x. Duration è stato sostituito con MaxDurationMs, MinDurationMs e AvgDurationMs. Success Rate è stato anche rinominato in Success Rate.

Considerazioni per Hub di Azure Stack

Il Servizio app in Hub di Azure Stack non supporta la versione 4.x di Funzioni di Azure. Quando si pianifica una migrazione dalla versione 1.x in Hub di Azure Stack, è possibile scegliere una delle opzioni seguenti:

  • Eseguire la migrazione alla versione 4.x ospitata in Funzioni di Azure nel cloud pubblico seguendo le istruzioni riportate in questo articolo. Invece di aggiornare l'app esistente, creare una nuova app usando la versione 4.x e quindi distribuirvi il progetto modificato.
  • Passare a WebJobs ospitati in un piano di servizio app In Hub di Azure Stack.

Passaggi successivi

Altre informazioni sulle versioni di Funzioni