Migrer des applications d’Azure Functions version 3.x vers la version 4.x

Ces étapes supposent un projet C# local, et si votre application utilise plutôt un script C# (fichiers .csx), vous devez convertir en modèle de projet avant de continuer.

Les modifications suivantes sont requises dans le fichier projet XML .csproj :

1. Définissez la valeur de PropertyGroup.TargetFramework en net8.0.

2. Définissez la valeur de PropertyGroup.AzureFunctionsVersion en v4.

3. Ajoutez l’élément OutputType suivant au PropertyGroup :

   <OutputType>Exe</OutputType>
   

4. Dans la liste ItemGroup.PackageReference, remplacez la référence de package par Microsoft.NET.Sdk.Functions avec les références suivantes :

     <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" />
   

   Notez toute référence à d’autres packages dans les espaces de noms Microsoft.Azure.WebJobs.*. Vous remplacerez ces packages dans une étape ultérieure.

5. Ajoutez le nouveau ItemGroup suivant :

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

Une fois ces modifications effectuées, votre projet mis à jour doit ressembler à l’exemple suivant :

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

Ces étapes supposent un projet C# local, et si votre application utilise plutôt un script C# (fichiers .csx), vous devez convertir en modèle de projet avant de continuer.

Les modifications suivantes sont requises dans le fichier projet XML .csproj :

1. Définissez la valeur de PropertyGroup.TargetFramework en net48.

2. Définissez la valeur de PropertyGroup.AzureFunctionsVersion en v4.

3. Ajoutez l’élément OutputType suivant au PropertyGroup :

   <OutputType>Exe</OutputType>
   

4. Dans la liste ItemGroup.PackageReference, remplacez la référence de package par Microsoft.NET.Sdk.Functions avec les références suivantes :

     <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" />
   

   Notez toute référence à d’autres packages dans les espaces de noms Microsoft.Azure.WebJobs.*. Vous remplacerez ces packages dans une étape ultérieure.

5. Ajoutez le nouveau ItemGroup suivant :

   <ItemGroup>
     <Folder Include="Properties\" />
   </ItemGroup>
   

Une fois ces modifications effectuées, votre projet mis à jour doit ressembler à l’exemple suivant :

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

Les modifications suivantes sont requises dans le fichier projet XML .csproj :

1. Définissez la valeur de PropertyGroup.TargetFramework en net8.0.

2. Définissez la valeur de PropertyGroup.AzureFunctionsVersion en v4.

3. Remplacez la liste ItemGroup.PackageReference existante par le ItemGroup suivant :

   <ItemGroup>
     <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="4.4.0" />
   </ItemGroup>
   

Une fois ces modifications effectuées, votre projet mis à jour doit ressembler à l’exemple suivant :

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

Si ce n’est déjà fait, mettez à jour votre projet pour référencer les dernières versions stables de :

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

En fonction des déclencheurs et des liaisons que votre application utilise, elle pourrait avoir besoin de référencer un ensemble de packages différent. Le tableau suivant présente des remplacements à certaines des extensions les plus couramment utilisées :

Consultez les Liaisons prises en charge pour la liste complète des extensions à prendre en compte, et référez-vous à la documentation de chaque extension pour obtenir des instructions d’installation complètes du modèle de processus isolé. Veillez à installer la dernière version stable de tous les packages que vous ciblez.

Votre application de modèle Worker isolé ne doit pas référencer de packages dans l’espace de noms Microsoft.Azure.WebJobs.* ni Microsoft.Azure.Functions.Extensions. S’il reste des références à ces derniers, elles doivent être supprimées.

Si ce n’est déjà fait, mettez à jour votre projet pour référencer les dernières versions stables de :

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

En fonction des déclencheurs et des liaisons que votre application utilise, elle pourrait avoir besoin de référencer un ensemble de packages différent. Le tableau suivant présente des remplacements à certaines des extensions les plus couramment utilisées :

Consultez les Liaisons prises en charge pour la liste complète des extensions à prendre en compte, et référez-vous à la documentation de chaque extension pour obtenir des instructions d’installation complètes du modèle de processus isolé. Veillez à installer la dernière version stable de tous les packages que vous ciblez.

Votre application de modèle Worker isolé ne doit pas référencer de packages dans l’espace de noms Microsoft.Azure.WebJobs.* ni Microsoft.Azure.Functions.Extensions. S’il reste des références à ces derniers, elles doivent être supprimées.

Mettez à jour votre projet pour référencer la dernière version stable de Microsoft.NET.Sdk.Functions.

Selon les déclencheurs et les liaisons que votre application utilise, celle-ci peut avoir besoin de référencer un ensemble supplémentaire de packages. Consultez Liaisons prises en charge pour obtenir une liste des extensions à prendre en compte, et consultez la documentation de chaque extension pour obtenir des instructions d’installation complètes du modèle de processus In-process. Veillez à installer la dernière version stable de tous les packages que vous ciblez.

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();

Cet exemple inclut l’intégration d’ASP.NET Core pour améliorer les performances et fournir un modèle de programmation familier lorsque votre application utilise des déclencheurs HTTP. Si vous n’avez pas l’intention d’utiliser des déclencheurs HTTP, vous pouvez remplacer l’appel à ConfigureFunctionsWebApplication par un appel à ConfigureFunctionsWorkerDefaults. Dans ce cas, vous pouvez supprimer la référence à Microsoft.Azure.Functions.Worker.Extensions.Http.AspNetCore de votre fichier projet. Toutefois, pour des performances optimales, même pour les fonctions avec d’autres types de déclencheurs, vous devez conserver ASP.NET Core comme FrameworkReference.

Le fichier Program.cs remplace n’importe quel fichier qui a l’attribut FunctionsStartup, qui est généralement un fichier Startup.cs. Dans les endroits où votre code FunctionsStartup référence IFunctionsHostBuilder.Services, vous pouvez à la place ajouter des instructions dans la méthode .ConfigureServices() de HostBuilder dans votre Program.cs. Pour en savoir plus sur l’utilisation de Program.cs, consultez Démarrage et configuration dans le guide de modèle Worker isolé.

Les exemples Program.cs par défaut ci-dessus incluent la configuration de l’intégration d’Application Insights pour le modèle Worker isolé. Dans votre Program.cs, vous devez également configurer tout filtrage des journaux qui doit s’appliquer aux journaux provenant du code dans votre projet. Dans le modèle Worker isolé, le fichier host.json contrôle uniquement les événements émis par le runtime hôte Functions. Si vous ne configurez pas de règles de filtrage dans Program.cs, vous constaterez peut-être des différences dans les niveaux de journalisation présents pour les différentes catégories de votre télémétrie.

Bien que vous puissiez enregistrer des sources de configuration personnalisées dans le cadre du HostBuilder, notez que celles-ci s’appliquent également uniquement au code de votre projet. La configuration des déclencheurs et des liaisons est également requise par la plateforme, et elle doit être fournie via les paramètres d’application, les références Key Vault ou les fonctionnalités de références App Configuration.

Une fois que vous avez déplacé tous les éléments FunctionsStartup existants vers le fichier Program.cs, vous pouvez supprimer l’attribut FunctionsStartup et la classe à laquelle elle a été appliquée.

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();
        }
    }
}

Le fichier Program.cs remplace n’importe quel fichier qui a l’attribut FunctionsStartup, qui est généralement un fichier Startup.cs. Dans les endroits où votre code FunctionsStartup référence IFunctionsHostBuilder.Services, vous pouvez à la place ajouter des instructions dans la méthode .ConfigureServices() de HostBuilder dans votre Program.cs. Pour en savoir plus sur l’utilisation de Program.cs, consultez Démarrage et configuration dans le guide de modèle Worker isolé.

Les exemples Program.cs par défaut ci-dessus incluent la configuration de l’intégration d’Application Insights pour le modèle Worker isolé. Dans votre Program.cs, vous devez également configurer tout filtrage des journaux qui doit s’appliquer aux journaux provenant du code dans votre projet. Dans le modèle Worker isolé, le fichier host.json contrôle uniquement les événements émis par le runtime hôte Functions. Si vous ne configurez pas de règles de filtrage dans Program.cs, vous constaterez peut-être des différences dans les niveaux de journalisation présents pour les différentes catégories de votre télémétrie.

Bien que vous puissiez enregistrer des sources de configuration personnalisées dans le cadre du HostBuilder, notez que celles-ci s’appliquent également uniquement au code de votre projet. La configuration des déclencheurs et des liaisons est également requise par la plateforme, et elle doit être fournie via les paramètres d’application, les références Key Vault ou les fonctionnalités de références App Configuration.

Une fois que vous avez déplacé tous les éléments FunctionsStartup existants vers le fichier Program.cs, vous pouvez supprimer l’attribut FunctionsStartup et la classe à laquelle elle a été appliquée.

Un fichier Program.cs n’est pas obligatoire lorsque vous utilisez le modèle 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"
    }
}

Aucune modification n’est requise pour votre fichier host.json. Toutefois, si votre configuration Application Insights dans ce fichier provient de votre projet de modèle in-process, vous souhaiterez peut-être apporter des modifications supplémentaires à votre fichier Program.cs. Le fichier host.json contrôle uniquement la journalisation à partir du runtime de l’hôte Functions, et dans le modèle Worker isolé, certains de ces journaux proviennent directement de votre application, vous donnant plus de contrôle. Pour plus d’informations sur la façon de filtrer ces journaux, consultez Gestion des niveaux de journal dans le modèle Worker isolé.

Aucune modification n’est requise pour votre fichier host.json. Toutefois, si votre configuration Application Insights dans ce fichier provient de votre projet de modèle in-process, vous souhaiterez peut-être apporter des modifications supplémentaires à votre fichier Program.cs. Le fichier host.json contrôle uniquement la journalisation à partir du runtime de l’hôte Functions, et dans le modèle Worker isolé, certains de ces journaux proviennent directement de votre application, vous donnant plus de contrôle. Pour plus d’informations sur la façon de filtrer ces journaux, consultez Gestion des niveaux de journal dans le modèle Worker isolé.

Aucune modification n’est requise pour votre fichier host.json.

Cette section met en évidence d’autres modifications du code à prendre en compte lors de la migration. Ces modifications ne sont pas nécessaires à toutes les applications, mais vous devez évaluer si certaines sont pertinentes pour vos scénarios. Veillez à consulter Changements cassants entre la version 3.x et la version 4.x afin de connaître les modifications supplémentaires que vous devrez peut-être apporter à votre projet.

Sérialisation JSON

Par défaut, le modèle Worker isolé utilise System.Text.Json pour la sérialisation JSON. Pour personnaliser les options de sérialiseur ou passer à JSON.NET (Newtonsoft.Json), consultez ces instructions.

Niveaux de journalisation et filtrage Application Insights

Les journaux peuvent être envoyés à Application Insights à partir du runtime de l’hôte Functions et du code de votre projet. Le host.json vous permet de configurer des règles pour la journalisation de l’hôte, mais pour contrôler les journaux provenant de votre code, vous devrez configurer des règles de filtrage dans le cadre de votre Program.cs. Pour plus d’informations sur la façon de filtrer ces journaux, consultez Gestion des niveaux de journal dans le modèle Worker isolé.

Cette section met en évidence d’autres modifications du code à prendre en compte lors de la migration. Ces modifications ne sont pas nécessaires à toutes les applications, mais vous devez évaluer si certaines sont pertinentes pour vos scénarios. Veillez à consulter Changements cassants entre la version 3.x et la version 4.x afin de connaître les modifications supplémentaires que vous devrez peut-être apporter à votre projet.

Sérialisation JSON

Par défaut, le modèle Worker isolé utilise System.Text.Json pour la sérialisation JSON. Pour personnaliser les options de sérialiseur ou passer à JSON.NET (Newtonsoft.Json), consultez ces instructions.

Niveaux de journalisation et filtrage Application Insights

Les journaux peuvent être envoyés à Application Insights à partir du runtime de l’hôte Functions et du code de votre projet. Le host.json vous permet de configurer des règles pour la journalisation de l’hôte, mais pour contrôler les journaux provenant de votre code, vous devrez configurer des règles de filtrage dans le cadre de votre Program.cs. Pour plus d’informations sur la façon de filtrer ces journaux, consultez Gestion des niveaux de journal dans le modèle Worker isolé.

Veillez à consulter Changements cassants entre la version 3.x et la version 4.x afin de connaître les modifications supplémentaires que vous devrez peut-être apporter à votre projet.

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;
        }
    }
}

Identique à la version 3.x (in-process).