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

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. Nel ItemGroup.PackageReference elenco, 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>

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 net48.

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

3. Aggiungere l'elemento OutputType seguente a PropertyGroup:

   <OutputType>Exe</OutputType>
   

4. Nel ItemGroup.PackageReference elenco, sostituire il riferimento al pacchetto a Microsoft.NET.Sdk.Functions con i riferimenti seguenti:

     <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
     <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
     <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>
     <Folder Include="Properties\" />
   </ItemGroup>
   

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

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <AzureFunctionsVersion>v4</AzureFunctionsVersion>
    <RootNamespace>My.Namespace</RootNamespace>
    <OutputType>Exe</OutputType>
  </PropertyGroup>
  <ItemGroup>
      <PackageReference Include="Microsoft.Azure.Functions.Worker" Version="1.21.0" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Sdk" Version="1.16.4" />
      <PackageReference Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
      <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>
    <Folder Include="Properties\" />
  </ItemGroup>
</Project>

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. Sostituire il ItemGroupesistente.PackageReference elenco con il ItemGroup seguente:

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </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>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
  </ItemGroup>
  <ItemGroup>
    <None Update="host.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
    </None>
    <None Update="local.settings.json">
      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
      <CopyToPublishDirectory>Never</CopyToPublishDirectory>
    </None>
  </ItemGroup>
</Project>

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

• Microsoft.Azure.Functions.Worker
• Microsoft.Azure.Functions.Worker.Sdk

A seconda dei trigger e delle associazioni usate 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:

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.

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.

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

• Microsoft.Azure.Functions.Worker
• Microsoft.Azure.Functions.Worker.Sdk

A seconda dei trigger e delle associazioni usate 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:

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.

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.

Aggiornare il progetto per fare riferimento alla versione stabile più recente di Microsoft.NET.Sdk.Functions.

A seconda dei trigger e delle associazioni usate dall'app, è possibile che l'app debba fare riferimento a un set aggiuntivo di pacchetti. 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 In-Process. Accertarsi di installare la versione stabile più recente di ogni pacchetto di destinazione.

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.

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

namespace Company.FunctionApp
{
    internal class Program
    {
        static void Main(string[] args)
        {
            FunctionsDebugger.Enable();

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

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.

Un file Program.cs non è necessario quando si usa il modello in-process.

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

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

{
    "IsEncrypted": false,
    "Values": {
        "AzureWebJobsStorage": "AzureWebJobsStorageConnectionStringValue",
        "FUNCTIONS_WORKER_RUNTIME": "dotnet",
        "FUNCTIONS_INPROC_NET8_ENABLED": "1"
    }
}

Non sono necessarie modifiche al file host.json. Tuttavia, se la configurazione di Application Insights è contenuta in questo file dal progetto di modello in-process, può essere necessario apportare modifiche aggiuntive nel file Program.cs. 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.

Non sono necessarie modifiche al file host.json. Tuttavia, se la configurazione di Application Insights è contenuta in questo file dal progetto di modello in-process, può essere necessario apportare modifiche aggiuntive nel file Program.cs. 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.

Non sono necessarie modifiche al file host.json.

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. Assicurarsi di controllare Modifiche di rilievo tra 3.x e 4.x per eventuali modifiche aggiuntive 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.

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. Assicurarsi di controllare Modifiche di rilievo tra 3.x e 4.x per eventuali modifiche aggiuntive 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.

Assicurarsi di controllare Modifiche di rilievo tra 3.x e 4.x per eventuali modifiche aggiuntive che potrebbe essere necessario apportare al progetto.

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"]}!");
        }
    }
}

using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Http;
using Microsoft.Extensions.Logging;
using System.Net;

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

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

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

            var response = req.CreateResponse(HttpStatusCode.OK);
            response.Headers.Add("Content-Type", "text/plain; charset=utf-8");

            response.WriteString($"Welcome to Azure Functions, {req.Query["name"]}!");

            return response;
        }
    }
}

Corrisponde alla versione 3.x (in-process).