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. Forse si sta cercando di eseguire la migrazione dell'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 precedente.

Importante

TypeScript non è supportato dalla versione 1.x del runtime di Funzioni di Azure. Forse si sta cercando di eseguire la migrazione dell'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 precedente.

Importante

PowerShell non è supportato dalla versione 1.x del runtime di Funzioni di Azure. In alternativa, si sta cercando di eseguire la migrazione dell'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 precedente.

Importante

Python non è supportato dalla versione 1.x del runtime di Funzioni di Azure. In alternativa, si sta cercando di eseguire la migrazione dell'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 precedente.

Importante

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

Questo articolo illustra il processo di migrazione sicura dell'app per le funzioni da eseguire nella versione 4.x del runtime di Funzioni. Poiché le istruzioni di migrazione del progetto dipendono dal linguaggio, assicurarsi di scegliere il linguaggio di sviluppo dal selettore nella parte superiore dell'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 di 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 il progetto C# a una delle versioni seguenti di .NET supportate da Funzioni versione 4.x:

Versione di .NET Tipo di versione dei criteri di supporto ufficiale di .NET Modello di processodi Funzioni 1,3
.NET 82 LTS Modello di lavoro isolato
.NET 7 STS (fine del supporto 14 maggio 2024) Modello di lavoro isolato
.NET 6 LTS (fine del supporto 12 novembre 2024) Modello di lavoro isolato,
Modello in-process3
.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 Standard Term Support (STS) di .NET, oltre a .NET Framework. Il modello in-process supporta solo le versioni LTS di .NET. Per un confronto completo di funzionalità e funzionalità tra i due modelli, vedere Differenze tra processi in-process e isolare il processo di lavoro .NET Funzioni di Azure.

2 .NET 8 non è ancora supportato nel modello in-process, anche se è disponibile nel modello di lavoro isolato. Per informazioni sui piani .NET 8, incluse le opzioni future per il modello in-process, vedere il post relativo all'aggiornamento della roadmap Funzioni di Azure.

3 Il supporto termina per il modello in-process il 10 novembre 2026. Per altre informazioni, vedere questo annuncio di supporto. Per un supporto completo continuo, è consigliabile eseguire la migrazione delle app al modello di lavoro isolato.

Suggerimento

A meno che l'app non dipende da una libreria o da un'API disponibile solo per .NET Framework, è consigliabile eseguire l'aggiornamento a .NET 8 nel modello di lavoro isolato. Molte app nella versione 1.x sono destinate solo a .NET Framework perché è ciò che era disponibile al momento della creazione. 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, è consigliabile usare una versione più recente. .NET 8 è la versione completamente rilasciata con la finestra di supporto più lunga di .NET.

Sebbene sia possibile scegliere di usare invece il modello in-process, questo non è consigliato se può essere evitato. Il supporto terminerà per il modello in-process il 10 novembre 2026, quindi sarà necessario passare al modello di lavoro isolato prima di allora. In questo modo, durante la migrazione alla versione 4.x, si ridurrà il lavoro totale richiesto e il modello di lavoro isolato offrirà all'app vantaggi aggiuntivi, inclusa la possibilità di usare versioni future di .NET con maggiore facilità. Se si passa al modello di lavoro isolato, . NET Upgrade Assistant può anche gestire molte delle modifiche di codice necessarie.

Questa guida non presenta esempi specifici per .NET 7 o .NET 6 nel modello di lavoro isolato. Se è necessario specificare come destinazione queste versioni, è possibile adattare gli esempi di modelli di lavoro isolati .NET 8.

Preparare la migrazione

Se non è già stato fatto, identificare l'elenco di app di cui è necessario eseguire la migrazione nella sottoscrizione di Azure corrente usando 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 di 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 del progetto locale per eseguire la migrazione del progetto locale alla versione 4.x.
  3. Dopo la migrazione del progetto, testare completamente l'app in locale usando la versione 4.x di Funzioni di Azure Core Tools.
  4. Aggiornare l'app per le funzioni in Azure alla nuova versione. Se è necessario ridurre al minimo i tempi di inattività, è consigliabile usare uno slot di staging per testare e verificare l'app migrata in Azure nella nuova versione di runtime. È quindi possibile distribuire l'app con le impostazioni di versione aggiornate nello slot di produzione. Per altre informazioni, vedere Aggiornare usando gli 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 in una versione precedente, viene richiesto 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 Update senza slot.

Eseguire la migrazione del progetto locale

Le sezioni seguenti descrivono gli aggiornamenti che è necessario apportare ai file di progetto C# per poter essere eseguiti 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, soprattutto 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 .NET Upgrade Assistant per apportare automaticamente molte delle modifiche indicate nelle sezioni seguenti.

File di progetto

L'esempio seguente è un .csproj file di progetto 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 il file XML da eseguire in Funzioni versione 4.x:

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

Nel file di .csproj progetto XML sono necessarie 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 seguente OutputType a PropertyGroup:

    <OutputType>Exe</OutputType>

  4. ItemGroupIn .PackageReference list, 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 Microsoft.Azure.WebJobs.* spazi dei nomi. Questi pacchetti verranno sostituiti in un passaggio successivo.

  5. Aggiungere il nuovo elemento ItemGroupseguente:

    <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 all'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 sulle using istruzioni negli esempi di modelli di trigger HTTP più avanti in questo articolo.

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

A seconda dei trigger e dei binding usati dall'app, l'app potrebbe dover fare riferimento a un set diverso di pacchetti. La tabella seguente illustra le sostituzioni per alcune delle estensioni più usate:

Scenario Modifiche ai riferimenti ai pacchetti
Trigger timer Aggiungi
Microsoft.Azure.Functions.Worker.Extensions.Timer
Associazioni di archiviazione Sostituzione
Microsoft.Azure.WebJobs.Extensions.Storage
con
Microsoft.Azure.Functions.Worker.Extensions. Archiviazione. BLOB,
Microsoft.Azure.Functions.Worker.Extensions. Archiviazione. Code e
Microsoft.Azure.Functions.Worker.Extensions.Tables
Associazioni di BLOB Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions. Archiviazione. Blob
Associazioni di code Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions. Archiviazione. Code
Associazioni di tabelle Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Tables
con la 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 la 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 la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Associazioni di Hub eventi Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.EventHubs
con la 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 la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Associazioni del Servizio SignalR Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.SignalRService
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Funzioni durevoli Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.DurableTask
con la 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 la 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 la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Associazioni SendGrid Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.SendGrid
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Associazioni Kafka Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.Kafka
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Binding RabbitMQ Sostituire i riferimenti a
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
con la versione più recente di
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Inserimento delle dipendenze
configurazione di avvio e avvio		 Rimuovere i riferimenti a
Microsoft.Azure.Functions.Extensions
Il modello di lavoro isolato fornisce questa funzionalità per impostazione predefinita.

Vedere Binding supportati per un elenco completo delle estensioni da considerare e consultare la documentazione di ogni estensione per istruzioni complete sull'installazione per il modello di processo isolato. Assicurarsi di installare la versione stabile più recente di tutti i pacchetti di destinazione.

Suggerimento

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

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

Suggerimento

L'app può anche dipendere dai tipi di Azure SDK, come parte dei trigger e delle associazioni o come dipendenza autonoma. È consigliabile sfruttare questa opportunità anche per aggiornare questi elementi. Le versioni più recenti delle estensioni di Funzioni funzionano con le versioni più recenti di Azure SDK per .NET, quasi tutti i pacchetti per i quali sono il formato 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 a favore dell'uso diretto di questi servizi usando gli SDK.

Program.cs file

Nella maggior parte dei casi, la migrazione richiede di aggiungere il 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 ASP.NET'integrazione core 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 questo 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, è consigliabile mantenere per FrameworkReference ASP.NET Core.

Il Program.cs file sostituirà qualsiasi file con l'attributo FunctionsStartup , che in genere è un Startup.cs file. Nelle posizioni in cui il FunctionsStartup codice fa riferimento IFunctionsHostBuilder.Servicesa , è invece possibile aggiungere istruzioni all'interno del .ConfigureServices() metodo di HostBuilder in Program.cs. Per altre informazioni sull'uso di Program.cs, vedere Start-up and configuration (Avvio e configurazione ) nella guida al modello di lavoro isolato.

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

Sebbene sia possibile registrare origini di configurazione personalizzate come parte di HostBuilder, si noti che si applicano in modo analogo solo al codice nel progetto. La configurazione dei trigger e dell'associazione è necessaria anche per la piattaforma e deve essere fornita tramite le impostazioni dell'applicazione, i riferimenti a Key Vault o Configurazione app funzionalità di riferimento.

Dopo aver spostato tutti gli elementi da qualsiasi esistente FunctionsStartup al Program.cs file, è possibile eliminare l'attributo FunctionsStartup e la classe a cui è stata applicata.

host.json file

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 ha valori di impostazione, esaminare il formato host.json v2 per eventuali modifiche.

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

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

Il host.json file 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.

local.settings.json file

Il file local.settings.json viene usato solo durante l'esecuzione in locale. Per informazioni, vedere File di impostazioni locali. Nella versione 1.x il file local.settings.json ha 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 abbia 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 FUNCTIONS_WORKER_RUNTIME valore in "dotnet-isolated".

Modifiche al nome della classe

Alcune classi chiave modificano i nomi tra la versione 1.x e la versione 4.x. Queste modifiche sono il risultato di una modifica delle API .NET o delle differenze tra processo in-process e processo di lavoro 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 di ASP.NET Core)
HttpResponseMessage HttpResponseData, IActionResult (usando l'integrazione di ASP.NET Core)

Potrebbero verificarsi anche differenze tra i nomi delle classi 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 è consigliabile valutare se sono rilevanti per gli scenari in uso. Assicurarsi 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.

Livelli e filtri dei 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 le regole per la registrazione dell'host, ma per controllare i log provenienti dal codice, è necessario configurare le 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 il progetto a Funzioni di Azure 4.x:

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

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

  3. Aggiungere entrambi version gli elementi e extensionBundle al host.json, in modo che abbia un aspetto simile all'esempio seguente:

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

    L'elemento extensionBundle è obbligatorio 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 l'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 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'aggiornare senza slot e quindi ripubblicare il progetto dell'app. È anche possibile ridurre al minimo i tempi di inattività nell'app e semplificare il rollback aggiornando gli slot.

Aggiornare senza slot

Il modo più semplice per eseguire l'aggiornamento a v4.x consiste nell'impostare l'impostazione ~4 dell'applicazione su nell'app per le FUNCTIONS_EXTENSION_VERSION 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>

È anche necessario impostare un'altra impostazione, che differisce tra Windows e Linux.

Quando si esegue in Windows, è anche necessario 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 qualsiasi linguaggio in esecuzione in Windows.

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

È ora possibile ripubblicare il progetto dell'app di cui è stata eseguita la migrazione per l'esecuzione nella versione 4.x.

Aggiornare usando gli slot

L'uso degli slot di distribuzione è un buon modo 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 di 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 tempo di inattività minimo.

Dopo aver verificato l'app nello slot aggiornato, puoi 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à di aggiunta di questa impostazione influisce sulla quantità di 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à, prendere in considerazione l'esecuzione di questa modifica al momento della riduzione del traffico. È quindi possibile scambiare la versione aggiornata dallo slot di staging.

Il Update-AzFunctionAppSetting cmdlet di PowerShell 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> con il nome dell'app per le funzioni e <RESOURCE_GROUP_NAME> con il nome del gruppo di risorse. Questo comando causa il riavvio dell'app nello slot di produzione.

  2. Usare il comando seguente per impostare WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS anche 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 di 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:

    Quando si esegue in Windows, è anche necessario 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 qualsiasi linguaggio in esecuzione in Windows.

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

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

  6. Verificare 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 nell'ambiente di produzione:

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

Aggiornamento 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 nell'ambiente di produzione. Successivamente, è possibile scambiare la versione aggiornata da uno slot di staging preavviso.

  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 di runtime da ripristinare durante la gestione temporanea. Questo errore può verificarsi perché la presenza WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di staging solo durante uno scambio rimuove l'impostazione FUNCTIONS_EXTENSION_VERSION nella gestione temporanea. 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, qualsiasi rollback dello scambio richiede anche la rimozione WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 diretta dall'ambiente di produzione prima dello scambio per evitare gli stessi errori nell'ambiente di produzione visualizzato nella gestione temporanea. Questa modifica nell'impostazione di produzione provocherebbe quindi un riavvio.

  3. Usare di nuovo il comando seguente per impostare WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 di nuovo 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 sono stati WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 impostati.

  4. Usare il comando seguente per modificare FUNCTIONS_EXTENSION_VERSION e aggiornare lo slot di staging alla nuova versione di 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:

    Quando si esegue in Windows, è anche necessario 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 qualsiasi linguaggio in esecuzione in Windows.

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

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

  7. Verificare 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 preavviso nell'ambiente di produzione:

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

Modifiche al comportamento dopo la versione 1.x

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

Modifiche apportate a trigger e binding

A partire dalla versione 2.x, è necessario installare le estensioni per trigger e associazioni specifici 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.

Esistono anche alcune modifiche nella function.json o attributi della funzione tra le versioni. Ad esempio, la proprietà Hub path 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 descrive in dettaglio le modifiche visualizzate 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 sono state archiviate 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.

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

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

  • Il formato URL dei webhook trigger di Griglia di eventi è stato modificato in modo da 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, MinDurationMse AvgDurationMs. Success Rate è stato anche rinominato in Success Rate.

Considerazioni sull'hub di Azure Stack

servizio app nell'hub di Azure Stack non supporta la versione 4.x di Funzioni di Azure. Quando si pianifica una migrazione dalla versione 1.x nell'hub di Azure Stack, è possibile scegliere una delle opzioni seguenti:

  • Eseguire la migrazione alla versione 4.x ospitata nel cloud pubblico Funzioni di Azure 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 Processi Web ospitati in un piano di servizio app nell'hub di Azure Stack.

Passaggi successivi

Altre informazioni sulle versioni di Funzioni