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

  • Article

Azure Functions version 4.x offre une compatibilité descendante forte avec la version 3.x. La plupart des applications doivent migrer en toute sécurité vers la version 4.x sans modification importante du code. Pour plus d’informations sur les versions du runtime Functions, consultez Vue d’ensemble des versions du runtime Azure Functions.

Important

Depuis le 13 décembre 2022, les applications de fonction exécutées sur les versions 2.x et 3.x du runtime Azure Functions ont atteint la fin du support étendu. Si vous souhaitez obtenir plus d’informations, consultez Versions mises hors services.

Cet article vous guide tout au long du processus de migration, de manière sécurisée, de votre application de fonction pour qu’elle s’exécute sur la version 4.x du runtime Functions. Étant donné que les instructions de migration du projet dépendent du langage, veillez à choisir votre langage de développement à l’aide du sélecteur en haut de l’article.

Identifier les applications de fonction à migrer

Utilisez le script PowerShell suivant pour générer une liste d’applications de fonction dans votre abonnement qui ciblent actuellement les versions 2.x ou 3.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 '*3*')
     {
          $AppInfo.Add($App.Name, $App.ApplicationSettings["FUNCTIONS_EXTENSION_VERSION"])
     }
}

$AppInfo

Choisissez votre version cible de .NET

Sur la version 3.x du runtime Functions, votre application de fonction C# cible .NET Core 3.1 à l'aide du modèle in-process ou .NET 5 à l'aide du modèle de travail isolé.

Lorsque vous migrez votre application de fonction, vous avez la possibilité de choisir la version cible de .NET. Vous pouvez mettre à jour votre projet C# vers l’une des versions suivantes de .NET, qui sont prises en charge par Functions version 4.x :

Version de .NET Type de version de la politique de prise en charge officielle .NET Modèle de processus Functions1,3
.NET 82 LTS Modèle de worker isolé
.NET 7 STS (fin de la prise en charge le 14 mai 2024) Modèle de worker isolé
.NET 6 LTS (fin de la prise en charge le 12 novembre 2024) Modèle de worker isolé,
Modèle in-process3
.NET Framework 4.8 Consulter la stratégie Modèle de worker isolé

1 Le modèle de worker isolé prend en charge les versions LTS (Long Term Support) et STS (Standard Term Support) de .NET, ainsi que .NET Framework. Le modèle in-process ne prend en charge que les versions LTS de .NET. Pour une comparaison complète des caractéristiques et des fonctionnalités entre les deux modèles, consultez Différences entre les processus .NET in-process et les processus de travail isolés Azure Functions.

2 .NET 8 n’est pas encore pris en charge sur le modèle In-process, bien qu’il soit disponible sur le modèle Worker isolé. Pour plus d’informations sur les plans .NET 8, y compris les options futures du modèle In-process, consultez le billet de mise à jour de la feuille de route Azure Functions.

3 La prise en charge prend fin pour le modèle in-process le 10 novembre 2026. Pour plus d’informations, lisez cette annonce relative à la prise en charge. Pour continuer à bénéficier d’une prise en charge complète, vous devez migrer vos applications vers le modèle Worker isolé.

Conseil

Nous vous recommandons de procéder à une mise à jour vers .NET 8 sur le modèle Worker isolé. .NET 8 est la version entièrement publiée avec la fenêtre de support la plus longue à partir de .NET.

Bien que vous puissiez choisir d’utiliser le modèle in-process, cela n’est pas recommandé si cela peut être évité. La prise en charge du modèle in-process prendra fin le 10 novembre 2026 ; vous devrez donc passer au modèle Worker isolé avant cette date. Le faire lors de la migration vers la version 4.x réduira l’effort total requis, et le modèle Worker isolé offrira à votre application des avantages supplémentaires, notamment la capacité à cibler plus facilement les futures versions de .NET. Si vous passez au modèle Worker isolé, l’Assistant Mise à niveau .NET peut également gérer bon nombre des modifications de code nécessaires pour vous.

Ce guide ne présente pas d’exemples spécifiques pour .NET 7 ou .NET 6 sur le modèle Worker isolé. Si vous devez cibler ces versions, vous pouvez adapter les exemples du modèle Worker isolé .NET 8.

Préparation de la migration

Si ce n’est pas déjà fait, identifiez la liste des applications qui doivent être migrées dans votre abonnement Azure actuel à l’aide d’Azure PowerShell.

Avant de migrer une application vers la version 4.x du runtime Functions, vous devez effectuer les tâches suivantes :

  1. Passez en revue la liste des changements cassants entre les versions 3.x et 4.x.
  2. Effectuez les étapes décrites dans Migrer votre projet local pour migrer votre projet local vers la version 4.x.
  3. Après avoir migré votre projet, testez entièrement l’application localement à l’aide de la version 4.x d’Azure Functions Core Tools.
  4. Exécutez le validateur de pré-mise à niveau sur l’application hébergée dans Azure et résolvez les problèmes identifiés.
  5. Mettez à jour votre application de fonction dans Azure vers la nouvelle version. Si vous devez réduire les temps d’arrêt, utilisez un emplacement de préproduction pour tester et vérifier votre application migrée dans Azure sur la nouvelle version du runtime. Vous pouvez ensuite déployer votre application avec les paramètres de version mis à jour sur l’emplacement de production. Pour plus d’informations, consultez Mettre à jour à l’aide d’emplacements.
  6. Publiez votre projet migré vers l’application de fonction mise à jour.

Lorsque vous utilisez Visual Studio pour publier un projet version 4.x sur une application de fonction existante qui a une version inférieure, vous êtes invité à laisser Visual Studio mettre à jour l’application de fonction vers la version 4.x pendant le déploiement. Cette mise à jour utilise le même processus que celui défini dans Mettre à jour sans emplacements.

Migrer votre projet local

Les instructions de mise à niveau dépendent du langage. Si vous ne voyez pas votre langage, sélectionnez-le à l’aide du sélecteur en haut de l’article.

Choisissez l’onglet qui correspond à votre version cible de .NET et au modèle de processus souhaité (in-process ou processus Worker isolé).

Conseil

Si vous passez à une version LTS ou STS de .NET à l’aide du modèle Worker isolé, vous pouvez utiliser l’Assistant Mise à niveau .NET pour apporter automatiquement bon nombre des modifications mentionnées dans les sections suivantes.

Fichier projet

L’exemple qui suit est un fichier projet .csproj qui utilise .NET Core 3.1 sur la version 3.x :

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AzureFunctionsVersion>v3</AzureFunctionsVersion>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.NET.Sdk.Functions" Version="3.0.13" />
  </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>

Appliquez l’une des procédures suivantes pour mettre à jour ce fichier XML afin qu’il s’exécute dans Functions 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>

Modifications apportées aux packages et aux espaces de noms

En fonction du modèle vers lequel vous migrez, vous pourriez avoir besoin de mettre à jour ou de modifier les packages que votre application référence. Lorsque vous adoptez les packages cibles, vous devrez mettre à jour l’espace de noms des instructions using et certains types que vous référencez. Vous pouvez voir l’effet de ces modifications d’espace de noms sur les instructions using contenues dans les exemples de modèles de déclencheur HTTP plus tard dans cet article.

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

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 :

Scénario Modifications apportées aux références de package
Déclencheur de minuteur Ajouter
Microsoft.Azure.Functions.Worker.Extensions.Timer
Liaisons de stockage Replace
Microsoft.Azure.WebJobs.Extensions.Storage
par
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs,
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues et
Microsoft.Azure.Functions.Worker.Extensions.Tables
liaisons SSL Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Storage.Blobs
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Blobs
Liaisons de la file d’attente Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Storage.Queues
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Storage.Queues
Liaisons de tableau Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Tables
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Tables
Liaisons Cosmos DB Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.CosmosDB
et/ou
Microsoft.Azure.WebJobs.Extensions.DocumentDB
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.CosmosDB
Liaisons Service Bus Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.ServiceBus
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.ServiceBus
Liaisons Event Hubs Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.EventHubs
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.EventHubs
Liaisons Event Grid Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.EventGrid
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.EventGrid
Liaisons SignalR Service Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.SignalRService
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.SignalRService
Fonctions durables Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.DurableTask
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask
Fonctions durables
(Fournisseur de stockage SQL)		 Remplacez les références à
Microsoft.DurableTask.SqlServer.AzureFunctions
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.SqlServer
Fonctions durables
(Fournisseur de stockage Netherite)		 Remplacez les références à
Microsoft.Azure.DurableTask.Netherite.AzureFunctions
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.DurableTask.Netherite
Liaisons SendGrid Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.SendGrid
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.SendGrid
Liaisons Kafka Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.Kafka
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.Kafka
Liaisons RabbitMQ Remplacez les références à
Microsoft.Azure.WebJobs.Extensions.RabbitMQ
par la version la plus récente de
Microsoft.Azure.Functions.Worker.Extensions.RabbitMQ
Injection de dépendances
et la configuration de démarrage		 Supprimez les références à
Microsoft.Azure.Functions.Extensions
(Le modèle Worker isolé fournit cette fonctionnalité par défaut.)

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.

Conseil

Toutes les modifications apportées aux versions d’extension pendant ce processus peuvent aussi vous obliger à mettre à jour votre fichier host.json. Veillez à lire la documentation de chaque extension que vous utilisez. Par exemple, l’extension Service Bus a des changements cassants dans la structure entre les versions 4.x et 5.x. Pour plus d’informations, consultez la section Liaisons Azure Service Bus pour Azure Functions.

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.

Conseil

Votre application peut également dépendre des types de kits de développement logiciel (SDK) Azure, soit dans le cadre de vos déclencheurs et liaisons, soit en tant que dépendance autonome. Vous devez également en profiter pour les mettre à jour. Les dernières versions des extensions Functions fonctionnent avec les dernières versions du kit de développement logiciel (SDK) Azure pour .NET, presque tous les packages dont la forme est Azure.*.

Fichier Program.cs

Lors de la migration vers une exécution dans un processus Worker isolé, vous devez ajouter le fichier program.cs suivant à votre projet :

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.

Fichier local.settings.json

Le fichier local.settings.json est uniquement utilisé lors de l’exécution locale. Pour en savoir plus, consultez Fichier de paramètres locaux.

Lorsque vous effectuez une migration vers la version 4.x, vérifiez que votre fichier local.settings.json contient au moins les éléments suivants :

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

Remarque

Lors de la migration d’un processus d’exécution In-process vers un processus d’exécution Worker isolé, vous devez passer la valeur FUNCTIONS_WORKER_RUNTIME à « dotnet-isolated ».

Fichier host.json

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

Modifications de nom de classe

Certaines classes principales ont changé de nom entre les versions. Ces modifications sont la conséquence de modifications apportées aux API .NET ou de différences entre l’exécution in-process et le processus Worker isolé. Le tableau suivant indique les classes principales .NET utilisées par Functions qui sont susceptibles de changer lors de la migration :

.NET Core 3.1 .NET 5 .NET 8
FunctionName (attribut) Function (attribut) Function (attribut)
ILogger ILogger ILogger, ILogger<T>
HttpRequest HttpRequestData HttpRequestData, HttpRequest (à l’aide de l’intégration ASP.NET Core)
IActionResult HttpResponseData HttpResponseData, IActionResult (à l’aide de l’intégration ASP.NET Core)
FunctionsStartup (attribut) Utilise Program.cs à la place Utilise Program.cs à la place

Il peut également y avoir des différences de nom de classe dans les liaisons. Pour plus d’informations, consultez les articles de référence relatifs aux liaisons en question.

Autres modifications du code

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

Modèle de déclencheur HTTP

Les différences entre in-process et processus Worker isolé sont visibles dans les fonctions déclenchées par HTTP. Le modèle de déclencheur HTTP pour la version 3.x (in-process) ressemble à l’exemple suivant :

using System;
using System.IO;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Newtonsoft.Json;

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

            string name = req.Query["name"];

            string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
            dynamic data = JsonConvert.DeserializeObject(requestBody);
            name = name ?? data?.name;

            string responseMessage = string.IsNullOrEmpty(name)
                ? "This HTTP triggered function executed successfully. Pass a name in the query string or in the request body for a personalized response."
                : $"Hello, {name}. This HTTP triggered function executed successfully.";

            return new OkObjectResult(responseMessage);
        }
    }
}

Le modèle de déclencheur HTTP pour la version migrée ressemble à l’exemple suivant :

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

Pour mettre à jour votre projet vers Azure Functions 4.x :

  1. Mettez à jour votre installation locale de Azure Functions Core Tools vers la version 4.x.

  2. Mettez à jour le bundle d’extensions Azure Functions de votre application vers la version 2.x ou ultérieure. Pour plus d'informations, consultez Modifications importantes.

  1. Si nécessaire, passez à l’une des versions java prises en charge sur la version 4.x.

  2. Mettez à jour le fichier POM.xml de l’application en affectant la valeur ~4 au paramètre FUNCTIONS_EXTENSION_VERSION, comme dans l’exemple suivant :

    <configuration>
    <resourceGroup>${functionResourceGroup}</resourceGroup>
    <appName>${functionAppName}</appName>
    <region>${functionAppRegion}</region>
    <appSettings>
        <property>
            <name>WEBSITE_RUN_FROM_PACKAGE</name>
            <value>1</value>
        </property>
        <property>
            <name>FUNCTIONS_EXTENSION_VERSION</name>
            <value>~4</value>
        </property>
    </appSettings>
</configuration>
  1. Si nécessaire, passez à l’une des versions Node.js prises en charge sur la version 4.x.
  1. Profitez de cette opportunité pour effectuer une mise à niveau vers PowerShell 7.2, est recommandée. Pour plus d’informations, consultez Versions de PowerShell.
  1. Si vous utilisez Python 3.6, passez à l’une des versions prises en charge.

Exécuter le validateur de pré-mise à niveau

Azure Functions fournit un validateur de pré-mise à niveau pour vous aider à identifier les problèmes potentiels lors de la migration de votre application de fonction vers la version 4.x. Pour exécuter le validateur de pré-mise à niveau :

  1. Sur le portail Azure, accédez à votre application de fonction.

  2. Ouvrez la page Diagnostiquer et résoudre les problèmes.

  3. Dans Diagnostics de l’application de fonction, commencez à taper Functions 4.x Pre-Upgrade Validator, puis choisissez-le dans la liste.

  4. Une fois la validation terminée, passez en revue les recommandations et résolvez les problèmes dans votre application. Si vous devez apporter des modifications à votre application, veillez à valider les modifications par rapport à la version 4.x du runtime Functions, soit localement à l’aide d’Azure Functions Core Tools v4, soit à l’aide d’un emplacement de préproduction.

Mettre à jour votre application de fonction dans Azure

Vous devez mettre à jour le runtime de l’hôte d’application de fonction dans Azure vers la version 4.x avant de publier votre projet migré. La version du runtime utilisée par l’hôte Functions est contrôlée par le paramètre d’application FUNCTIONS_EXTENSION_VERSION, mais dans certains cas d’autres paramètres doivent également être mis à jour. Les modifications de code et les modifications apportées aux paramètres d’application nécessitent le redémarrage de votre application de fonction.

Le moyen le plus simple de procéder consiste à mettre à jour sans emplacements, puis à republier votre projet d’application. Vous pouvez également réduire le temps d’arrêt dans votre application et simplifier la restauration en effectuant une mise à jour à l’aide d’emplacements.

Mettre à jour sans emplacements

Le moyen le plus simple de mettre à jour vers la version v4.x consiste à affecter la valeur ~4 au paramètre d’application FUNCTIONS_EXTENSION_VERSION sur votre application de fonction dans Azure. Vous devez suivre une procédure différente sur un site avec des emplacements.

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

Vous devez également définir un autre paramètre, qui diffère entre Windows et Linux.

Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

.NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

Vous pouvez maintenant republier votre projet d’application qui a été migré pour s’exécuter sur la version 4.x.

Mettre à jour à l’aide d’emplacements

L’utilisation d’emplacements de déploiement est un bon moyen de mettre à jour votre application de fonction vers le runtime v4.x à partir d’une version précédente. À l’aide d’un emplacement de préproduction, vous pouvez exécuter votre application sur la nouvelle version du runtime dans l’emplacement de préproduction et basculer vers la production après vérification. Les emplacements permettent également de réduire les temps d’arrêt pendant la mise à jour. Si vous devez réduire au maximum les temps d’arrêt, suivez les étapes de Mise à jour avec un minimum de temps d’arrêt.

Une fois que vous avez vérifié votre application dans l’emplacement mis à jour, vous pouvez basculer l’application et les nouveaux paramètres de version en production. Cet échange nécessite un paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de production. La façon dont vous ajoutez ce paramètre affecte la durée de temps d’arrêt nécessaire pour la mise à jour.

Mise à jour standard

Si votre application de fonction avec emplacement peut gérer le temps d’arrêt d’un redémarrage complet, vous pouvez mettre à jour le paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS directement dans l’emplacement de production. Étant donné que la modification de ce paramètre directement dans l’emplacement de production entraîne un redémarrage qui a un impact sur la disponibilité, envisagez de procéder à cette modification au moment de la réduction du trafic. Vous pouvez ensuite permuter la version mise à jour à partir de l’emplacement de préproduction.

L’applet de commande PowerShell Update-AzFunctionAppSetting ne prend pas actuellement en charge les emplacements. Vous devez utiliser Azure CLI ou le portail Azure.

  1. Utilisez la commande suivante pour définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de production :

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

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources. Cette commande entraîne le redémarrage de l’application dans l’emplacement de production.

  2. Utilisez la commande suivante pour définir également WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS dans l’emplacement de préproduction :

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

  3. Utilisez la commande suivante pour modifier FUNCTIONS_EXTENSION_VERSION et mettre à jour l’emplacement de préproduction vers la nouvelle version du runtime :

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

  4. La version 4.x du runtime Functions nécessite .NET 6 dans Windows. Sur Linux, les applications .NET doivent également être mises à jour vers .NET 6. Utilisez la commande suivante pour que le runtime puisse s’exécuter sur .NET 6 :

    Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

    .NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

  5. Si votre projet de code nécessite des mises à jour à exécuter sur la version 4.x, déployez ces mises à jour sur l’emplacement de préproduction maintenant.

  6. Vérifiez que votre application de fonction s’exécute correctement dans l’environnement intermédiaire mis à jour avant d’effectuer la permutation.

  7. Utilisez la commande suivante pour faire basculer l’emplacement de préproduction mis à jour en production :

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

Mise à jour avec un minimum de temps d’arrêt

Pour réduire le temps d’arrêt dans votre application de production, vous pouvez échanger le paramètre WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS de l’emplacement de préproduction en production. Après cela, vous pouvez permuter la version mise à jour à partir d’un emplacement de préproduction préchauffé.

  1. Utilisez la commande suivante pour définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de préproduction :

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

  2. Utilisez les commandes suivantes pour permuter l’emplacement avec le nouveau paramètre en production, et en même temps restaurer le paramètre de version dans l’emplacement de préproduction.

    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>

    Vous pouvez rencontrer des erreurs à partir de l’emplacement de préproduction pendant le délai entre l’échange et la version du runtime restaurée dans l’emplacement de préproduction. Cette erreur peut se produire, car avoir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 uniquement en préproduction pendant un échange supprime le paramètre FUNCTIONS_EXTENSION_VERSION dans l’emplacement de préproduction. Sans le paramètre de version, votre emplacement est dans un état incorrect. La mise à jour de la version dans l’emplacement de préproduction juste après l’échange doit remettre l’emplacement dans un état correct et vous pouvez restaurer vos modifications si nécessaire. Toutefois, toute restauration de l’échange vous oblige également à supprimer WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 directement de l’emplacement de production avant le retour de l’échange pour éviter les mêmes erreurs de production que celles observées en préproduction. Cette modification dans le paramètre de production entraîne alors un redémarrage.

  3. Utilisez la commande suivante pour à nouveau définir WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 dans l’emplacement de préproduction :

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

    À ce stade, WEBSITE_OVERRIDE_STICKY_EXTENSION_VERSIONS=0 est défini dans les deux emplacements.

  4. Utilisez la commande suivante pour modifier FUNCTIONS_EXTENSION_VERSION et mettre à jour l’emplacement de préproduction vers la nouvelle version du runtime :

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

  5. La version 4.x du runtime Functions nécessite .NET 6 dans Windows. Sur Linux, les applications .NET doivent également être mises à jour vers .NET 6. Utilisez la commande suivante pour que le runtime puisse s’exécuter sur .NET 6 :

    Lors de l’exécution sur Windows, vous devez également activer .NET 6.0, qui est requis par la version 4.x du runtime.

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

    .NET 6 est nécessaire pour les applications de fonction dans n’importe quel langage s’exécutant sur Windows.

    Dans cet exemple, remplacez <APP_NAME> par le nom de votre application de fonction, et <RESOURCE_GROUP_NAME> par le nom du groupe de ressources.

  6. Si votre projet de code nécessite des mises à jour à exécuter sur la version 4.x, déployez ces mises à jour sur l’emplacement de préproduction maintenant.

  7. Vérifiez que votre application de fonction s’exécute correctement dans l’environnement intermédiaire mis à jour avant d’effectuer la permutation.

  8. Utilisez la commande suivante pour faire basculer l’emplacement de préproduction mis à jour et préchauffé en production :

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

Changements cassants entre la version 3.x et la version 4.x

Voici les principales modifications cassants à prendre en compte avant de mettre à niveau une application 3.x vers la version 4.x, y compris les changements cassants spécifiques à la langue. Pour obtenir une liste complète, consultez les problèmes Azure Functions GitHub étiquetés Breaking Change: Approved (Changement cassant : Approuvé).

Si vous ne voyez pas votre langage de programmation, allez le sélectionner en haut de la page.

Runtime

  • Les Azure Functions Proxies sont une fonctionnalité héritée des versions 1.x à 3.x du runtime Azure Functions. La prise en charge de Functions Proxies peut être rétablie dans la version 4.x pour vous permettre de mettre à jour correctement vos applications de fonction vers la version du runtime la plus récente. Dès que possible, vous devez à la place basculer vers l’intégration de vos applications de fonction avec Gestion des API Azure. Gestion des API vous permet de tirer parti d’un ensemble plus complet de fonctionnalités pour définir, sécuriser, gérer et monétiser vos API basées sur Functions. Pour plus d’informations, consultez Intégration de Gestion des API. Pour savoir comment réactiver la prise en charge des Proxies dans Functions version 4.x, consultez Réactiver les Proxies dans Functions v4.x.

  • La journalisation vers Stockage Azure à l’aide d’AzureWebJobsDashboard n’est plus prise en charge dans la version 4.x. Vous devez plutôt utiliser Application Insights. (#1923)

  • Azure Functions 4.x applique désormais des exigences de version minimale pour les extensions. Effectuez une mise à jour vers la version la plus récente des extensions concernées. Pour les langages autres que .NET, effectuez une mise à jour vers la version 2.x ou ultérieure du pack d’extension. (#1987)

  • Les délais d’expiration par défaut et maximaux sont désormais appliqués dans la version 4.x pour les applications de fonction s’exécutant sur Linux dans un plan Consommation. (#1915)

  • Azure Functions 4.x utilise Azure.Identity et Azure.Security.KeyVault.Secrets pour le fournisseur Key Vault et a déconseillé l’utilisation de Microsoft.Azure.KeyVault. Pour plus d’informations sur la configuration des paramètres de l’application de fonction, consultez l’option Key Vault dans les référentiels de secrets. (#2048)

  • Les applications de fonction qui partagent des comptes de stockage ne démarrent plus lorsque leurs identifiants d’hôte sont les mêmes. Pour plus d’informations, consultez Considérations relatives à l’ID d’hôte. (#2049)

  • Azure Functions 4.x prend en charge les applications in-process et isolées .NET 6.

  • InvalidHostServicesException est désormais une erreur irrécupérable. (#2045)

  • EnableEnhancedScopes est activé par défaut. (#1954)

  • Supprimer HttpClient en tant que serveur inscrit. (#1911)

  • Utilisez le chargeur de classe unique dans Java 11. (#1997)

  • Arrêtez le chargement des fichiers JAR de Worker dans Java 8. (#1991)

  • Les versions 10 et 12 de Node.js ne sont pas prises en charge dans Azure Functions 4.x. (#1999)

  • La sérialisation de sortie dans les applications Node.js a été mise à jour pour résoudre les incohérences précédentes. (#2007)

  • Le nombre de Threads par défaut a été mis à jour. Les fonctions qui ne sont pas thread-safe ou qui ont une utilisation élevée de la mémoire pourraient être affectées. (#1962)

  • Python 3.6 n’est pas pris en charge dans Azure Functions 4.x. (#1999)

  • Le transfert de mémoire partagée est activé par défaut. (#1973)

  • Le nombre de Threads par défaut a été mis à jour. Les fonctions qui ne sont pas thread-safe ou qui ont une utilisation élevée de la mémoire pourraient être affectées. (#1962)

Étapes suivantes

En savoir plus sur les versions de Functions